> ## Documentation Index > Fetch the complete documentation index at: https://docs.impellabs.tech/llms.txt > Use this file to discover all available pages before exploring further. # Incoming events > Send events from your own system into ImpelLabs. 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. ```bash theme={null} 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. ```json theme={null} { "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..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](https://docs.impellabs.tech/api/webhooks.md#check-the-signature): `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. ```bash theme={null} 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..received` with this data. ```json theme={null} { "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](https://docs.impellabs.tech/api/webhooks.md). See [event types](https://docs.impellabs.tech/api/events.md). 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](https://docs.impellabs.tech/api/forms-and-leads.md). ## 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. ```bash theme={null} 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`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.