Incoming events

An incoming event is a request that your system sends to ImpelLabs. ImpelLabs checks it, keeps it once, and raises an event that a workflow can start on. A webhook can listen to the same event. You make one receiver for each sender. A receiver has its own address and its own secret. The secret is yours, and no other workspace can use it.

Make a receiver

Any member can read receivers. Only an owner or an admin can make, change, rotate or remove one.

curl -X POST https://api.impellabs.tech/api/v1/event-sources \
  -H "Authorization: Bearer imp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Order system",
    "verify": {"scheme": "token"}
  }'

The reply has status 201. It is the receiver, and it carries the secret once. Store it now.

{
  "id": "5d3c0f2a-0000-0000-0000-000000000000",
  "kind": "receive",
  "label": "Order system",
  "prefix": "order_system",
  "key": "received",
  "on": true,
  "address": "https://api.impellabs.tech/api/v1/events/in/5d3c0f2a-0000-0000-0000-000000000000",
  "url": "https://api.impellabs.tech/api/v1/events/in/5d3c0f2a-0000-0000-0000-000000000000",
  "scheme": "token",
  "header": "X-Impel-Token",
  "events": [{"name": "in.order_system.received", "label": "Order system"}],
  "secret_hint": "ab12",
  "secret": "whsec_..."
}

The request takes these fields.

Field	Rule
`label`	Up to 120 characters. The default is `Incoming webhook`.
`verify`	How ImpelLabs checks each request. See the next section.
`secret`	Optional. Your own secret, up to 200 characters. Use it when the sender has its own key. Without it, ImpelLabs makes one.
`id_path`	Optional. The path of the event id in the body, such as `order.id`.

The event name is in.<prefix>.received. The prefix comes from the label. It is unique in the workspace.

Task	Call
List the receivers.	`GET /api/v1/event-sources`
Read one.	`GET /api/v1/event-sources/{source_id}`
Switch it on or off with `on`, or rename it with `label`.	`PATCH /api/v1/event-sources/{source_id}`
Make a new secret. The old one stops at once. The reply is `{"source": {...}, "secret": "whsec_..."}`.	`POST /api/v1/event-sources/{source_id}/rotate`
Read the newest deliveries.	`GET /api/v1/event-sources/{source_id}/deliveries`
Archive it and switch it off.	`DELETE /api/v1/event-sources/{source_id}`

Choose how a request is checked

verify.scheme is one of these.

Scheme	What the sender does
`token`	Sends the secret as it is in a header. The default header is `X-Impel-Token`. Set `verify.header` for another name.
`hmac_sha256`	Sends an HMAC of the raw body with SHA-256, keyed by the secret, in `verify.header`.
`hmac_sha1`	The same with SHA-1.
`standard_webhooks`	Signs as in Webhooks: `webhook-id`, `webhook-timestamp` and `webhook-signature`.
`public`	Sends nothing. Use it only for a form on a public page. A sender address can send 20 requests an hour.

For hmac_sha256 and hmac_sha1, verify.header is required. You can also set verify.prefix (up to 20 characters, removed from the header before the check, such as sha256=) and verify.encoding (hex, the default, or base64). A bad verify returns 400 with the key verify.

Send an event

Send a POST with a JSON body, or with a form body (application/x-www-form-urlencoded). The body can be up to 256 KB.

curl -X POST https://api.impellabs.tech/api/v1/events/in/SOURCE_ID \
  -H "X-Impel-Token: whsec_..." \
  -H "X-Event-Id: order-1042" \
  -H "Content-Type: application/json" \
  -d '{"id": "order-1042", "total": 120, "customer": {"name": "Sam"}}'

The address needs no bearer token. The check of the scheme is the sign-in.

Status	Meaning
`202`	`Received.` ImpelLabs keeps the event and a worker raises it a moment later.
`200`	`Received before.` The same event id came earlier, so nothing is raised again. A receiver that is switched off also answers `200` and keeps nothing.
`400`	`Send JSON or a form.`
`401`	`The signature does not match.`
`404`	No receiver has this id, or it is archived.
`405`	Only `POST` is allowed.
`413`	`Too large.`
`429`	A `public` receiver got too many requests from one address.

ImpelLabs keeps each event once for each receiver and event id. It reads the id from the webhook-id header, then from the X-Event-Id header, then from id_path in the body. With none of them, it uses a hash of the body. Send a stable id so that a retry of yours is safe.

What ImpelLabs raises

For each stored request, ImpelLabs raises the event in.<prefix>.received with this data.

{
  "source_id": "5d3c0f2a-…",
  "connection_id": null,
  "delivery_id": "…",
  "event": "received",
  "object_id": "order-1042",
  "data": {"id": "order-1042", "total": 120, "customer": {"name": "Sam"}}
}

data is your body. object_id is the id key of the body, or empty. A body that is larger than 20000 characters once written as text is replaced by {"_cut": true}. The event is in the catalogue only while the receiver is on. Start a workflow on it, or choose it in a webhook. See event types. The list of deliveries shows what came and what it raised, never the body. Each item has id, external_id, status (received, done, refused or failed), event, error and at.

Lead sources

A lead source of the kind webhook is a receiver that also turns each event into a contact. It takes the same verify, secret and id_path. See forms and leads.

Events of a connected tool

When you connect a tool, ImpelLabs finds the events the tool can send, and the reads it can repeat on a schedule. Each one is off until you switch it on.

curl https://api.impellabs.tech/api/v1/connectors/CONNECTION_ID/events \
  -H "Authorization: Bearer imp_..."

curl -X PATCH https://api.impellabs.tech/api/v1/event-sources/SOURCE_ID \
  -H "Authorization: Bearer imp_..." \
  -H "Content-Type: application/json" \
  -d '{"on": true}'

An event that the tool sends to ImpelLabs has its own address and its own check. The reply of PATCH shows both. A read on a schedule takes every_minutes (1 to 1440) and sometimes an input. The tool must be connected with your own account. Switching on a read that needs an input that you did not give returns 400.

Get started

Resources

Events

Build

API reference