Webhooks

Give your agent a webhook URL so Zapier, Make, your own backend or any service that can send a web request can wake it with a payload and instructions.

Most automations run when something happens in a connected app, or on a schedule. A webhook automation covers the other cases. It gives you a unique URL, and any service that can send a web request (Zapier, Make, your own backend, a warehouse system) can POST data to it. Your agent wakes up with that data and follows the automation's instructions.

Use it when the thing that should wake your agent lives in an app eesel does not connect to directly, or when you want your own systems to hand work to your agent.

Setting one up

1

Ask for it in chat

Tell your agent what will be sending and what to do with each delivery. It creates the automation and hands you the URL to paste into the other app, along with the two optional headers below.

The agent hands out the URL and says what it will do with each payload.

You can also build one yourself on your agent's Automations page: choose When a webhook is received.

2

Check it on your Automations page

The automation is listed with Webhook received under its name, switched on.

The webhook automation, switched on.

Check it worked. From a terminal, eesel automations lists the automation as on.

3

Copy the URL

Open the automation. When it runs shows the URL with a Copy button, and the instructions sit below it.

Keep the URL private: anyone who has it can wake your agent, so share it only with the service that should call it. If it ever leaks, delete the automation and create a new one for a fresh URL.

The automation's page, with the URL and the instructions.

4

Point the other app at it

In Zapier that is a "Webhooks by Zapier" POST action. In your own code it is a plain HTTP POST. Send any JSON you like, and your agent reads all of it.

curl -X POST https://your-webhook-url \
  -H 'Content-Type: application/json' \
  -H 'X-Eesel-Event-Id: evt-88213' \
  -H 'X-Eesel-Reference: order-4711' \
  -H 'X-Eesel-Reference-Url: https://shop.example.com/admin/orders/4711' \
  -d '{"customer": "Sam", "message": "Order arrived damaged"}'

Send the headers whenever your app can. They are optional, but without them every row on your Activity page looks the same.

5

Check the result

Each delivery is a run on your Activity page: what arrived, what your agent did, and what it cost. When the instructions tell it to act in another app, the result is there too. In this example a shipment delay came in, the order could not be found in the store, and the agent opened a tagged ticket in Gorgias for the team.

The ticket the webhook run created in Gorgias.

Tell eesel what each delivery is

The three headers do different jobs.

Header	What it is	What it buys you
X-Eesel-Event-Id	Unique for this delivery, and the same value if you retry it	eesel processes the event exactly once, however many times your app sends it
X-Eesel-Reference	Stable for the thing the delivery is about: a conversation, ticket or order	Activity rows say which one they were about, instead of repeating the automation's name
X-Eesel-Reference-Url	Optional link to that thing in your own app	Turns the Activity row into a link straight back to it

The distinction matters when a single conversation sends several events. Each one needs its own event id, while they all share the same reference. Reusing one event id across them would look like a retry, and eesel would process only the first.

If you cannot set headers, a JSON body with an event_id or idempotency_key field still stops duplicate runs. Headers are the better option because they work for every kind of body. If you send form data or plain text rather than JSON, eesel keeps the body as it is for your agent to read, and a field inside it cannot be used as an event id.

Without any of this, eesel falls back to comparing whole payloads within the same day, which catches most retries but treats two identical events as one.

Only wake on the deliveries you want

By default every delivery wakes your agent. If only some deliveries matter, tell your agent in the dashboard chat which ones, for example "only act on deliveries where the delay is over 48 hours". It adds that to the automation. A delivery that does not match creates no run, is listed in the automation's activity as skipped, and is not billed.

Limits

• A body can be up to 1,000,000 bytes. Larger deliveries are rejected.

• A workspace can send 60 deliveries a minute. Above that the URL answers 429, and the sender should retry after a moment.

• eesel processes eight deliveries at a time. A burst beyond that also gets a 429, and the sender should retry.

• A paused automation answers deliveries with "skipped" and wakes nothing.

Good to know

• Pause instead of delete. The switch on the automation stops deliveries from waking your agent but keeps the URL. Deleting the automation retires its URL for good.

• Edits are safe. Changing the name or instructions never changes the URL, and the next delivery uses the new instructions.

• Billing works like other automation runs: each processed delivery is one run against your plan. A filtered-out delivery is not a run.

Related

• Automations and Schedules for event and scheduled automations

• Actions and Approvals for what happens when the run's action asks first

• The eesel CLI for eesel automations and eesel activity