# Custom signals

> Turn the events your own systems send into signals: what Funnel One records from each event, and how to build a signal on it.

A signal is Funnel One noticing something worth acting on about a company. Most
signals come from Funnel One's own sources. With [custom events](https://dev.funnelone.ai/rest/events/)
you can build signals on what happens in your own product too: a trial started,
a usage limit reached, a plan upgraded.

## From event to signal

1. Your system sends an event to `POST /api/v1/events`, naming a company or
   contact that is already in your workspace.
2. When it matches, Funnel One records a fact about that company called
   `custom_<name>`. An event named `trial_started` becomes
   `custom_trial_started`. Each property becomes a field called `prop.<key>`,
   so `plan` is `prop.plan`.
3. Your signal rules run on that fact the same way they run on every other one.

Each accepted event is recorded once, however many times you send it. An
`unmatched` event records nothing and fires nothing.

## Build a signal in Funnel One

1. Send at least one event with the name you want, so Funnel One knows the
   name and its properties. [`GET /api/v1/event-types`](https://dev.funnelone.ai/rest/events/#get-apiv1event-types)
   shows what it has.
2. In Funnel One, open **Signals** and create a signal.
3. Pick the event under the source **Your systems (API)**. It shows with its
   label, which starts as the name in words (`trial_started` shows as
   "Trial started").
4. Narrow it with the event's properties if you want to. For example, only
   `trial_started` events where `prop.plan` is `pro`.

A new name can take up to a minute to appear in the builder.

## What changes how an event counts

- **An old event does not start anything.** An event that arrives more than 24
  hours after its `occurred_at` still counts toward scoring and still fires
  signals, but it runs no alert, workflow or motion. Sending last month's
  history is safe.
- **An archived name** is still recorded, but it is hidden from the Signals
  builder.
- **A blocked name** is refused when it is sent (`event_blocked`), so it
  records nothing.
- **Your events are yours.** A signal only ever sees your own workspace's
  events. Another workspace sending the same name makes no difference to
  yours.

## Example

Your billing system sends this when a customer upgrades:

```json
{
  "id": "upgrade-8812",
  "name": "plan_upgraded",
  "company": { "domain": "acme.com" },
  "properties": { "plan": "enterprise", "seats": 40 }
}
```

A signal on **Plan upgraded** where `prop.plan` is `enterprise` now fires for
Acme, and you can score it, alert on it or start a motion from it like any
other signal.

Source: https://dev.funnelone.ai/rest/custom-signals/