Skip to main content

Webhook

Let other systems start automations by calling a URL, and send events, automation results and approved agent messages to a URL of yours.

The Webhook connection page

Incoming: start automations​

  1. Integrations → Add → Webhook.
  2. Under Incoming, turn on Receive calls and set an Incoming secret: any long random text.
  3. Save. The connection's URL appears.
  4. Make an automation that runs on Webhook received from this connection.

Callers POST to the URL, sending the secret in one of:

  • an Authorization: Bearer <secret> header,
  • an X-Webhook-Secret header,
  • a ?secret= query parameter.
curl -X POST "https://acme.example.com/api/webhooks/in/42/" \
-H "Authorization: Bearer $SECRET" \
-H "Content-Type: application/json" \
-d '{"order": 1042, "status": "delayed"}'

Use the URL shown on the connection. The body (up to 256 KB) is handed to the automation, and the call is answered 202 at once.

Outgoing: send calls to your URL​

Under Outgoing, turn on Send calls and set:

FieldWhat goes there
URLA public https address. Private and internal addresses are refused.
Signing secretSigns every call. Empty: calls are unsigned.
Events to sendEvents forwarded as they happen, from every connection.
Let agents sendAgents given this connection may propose a call; each waits for a person to approve it.

Automations can also send their results here.

Checking a call is ours​

Each call carries X-Webhook-Timestamp and X-Webhook-Signature: sha256=<hex>, the HMAC-SHA256 of <timestamp>.<body> with the signing secret. Recompute it, compare in constant time, and reject old timestamps:

import { createHmac, timingSafeEqual } from 'node:crypto';

function isOurs(secret, timestamp, body, signature) {
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = `sha256=${createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex')}`;
return expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}