Webhooks

Polling GET /v2/calls/{execution_id} in a loop is the wrong way to learn that a call finished — see Rate Limits. Point us at an HTTPS endpoint instead and we will post the finished call to it.

Every call produces one complete event, and several smaller ones on the way there. The complete one is all_processing_completed, fired after every piece of post-call processing has landed and carrying all 47 fields at once — it is the event to build on. Ahead of it come the progress events (call_ringing, call_started, call_completed, and the recording and analysis events), each carrying the 20-field envelope only.

A Custom Webhook set in the dashboard receives all of them. A subscription created with POST /v2/webhooks receives exactly the event types you name — use it when you want fewer.

Two ways to receive events

Both deliver the same payload, with the same signing, the same retry schedule and the same delivery log. Pick on how you want it configured, not on what you get.

There is no per-call webhook URL

POST /v2/calls takes no webhook_url. The destination is configured on the agent or on a subscription — never per request — which is what gives every event signing, automatic retries, and a delivery log you can inspect at GET /v2/webhooks/deliveries.

A per-call URL had none of those, and it pointed the call's own result callback somewhere else — which is how a call ends up connected, billed by the carrier, and never recorded on our side. Sending webhook_url in a call body is rejected with 1001 rather than ignored, so an older integration finds out on its first request instead of silently losing events.

For the same reason POST /v2/calls takes no provider. Which carrier places a call follows from the number and your organization's configuration.

Why one event and not two

The obvious design — fire when the call hangs up, then fire again when the recording is ready — is the design we deliberately do not ship by default.

A call does not finish producing data when it stops producing audio. At the moment the carrier reports the call terminal, we do not yet have the recording URL, the transcript, the cost breakdown or the sentiment analysis. Those arrive over the following seconds from three different producers. A "fire on hangup" webhook would therefore be a webhook with transcript: null, recording_url: null and call_cost: null in it — and you would have to poll anyway to get the parts you actually wanted. Firing again when each part lands means the same call is delivered to you four or five times and your handler has to reconcile partial states.

So the default subscription waits behind a barrier: the consolidated event is built and sent once, when the transcript, the cost, the recording and the analyses have all arrived — or when the barrier times out, whichever comes first.

The intermediate moments arrive as their own events, and they cost extra deliveries and the reconciliation that comes with them. A dashboard Custom Webhook receives them all; if that is more than your endpoint wants, create a subscription with POST /v2/webhooks naming only all_processing_completed — an agent-level subscription replaces the Custom Webhook entirely.

Event types

The six middle rows are the progress events. call_corrected is not one of them; it is a terminal-class event like the consolidated one.

call_corrected

Voicemail detection is not always instantaneous. A call can complete, be delivered to you as completed / ACCEPTED, and only afterwards be identified as having talked to an answering machine. When that happens we rewrite the record and send call_corrected carrying the corrected status and sub_status in the envelope, plus previous_status, previous_sub_status, correction_reason: "late_voicemail_verdict", call_cost: 0.0 and answered_by_voice_mail: true.

It carries the same call_id as the event you already stored. Treat it as an update to that row, not as a new call.

The default, and the empty-list rule

The resolved event list for any subscription is computed like this:

A subscription with enabled: false receives nothing, whatever its event list says.

Subscribing

Two request forms exist. They write the same documents; pick whichever fits the shape of your config.

curl -X POST https://api.graine.ai/v2/webhooks \
  -H "Authorization: Bearer gat_7f3c9a21b4e85d0c6a19f2734b8e5c60" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_5b7d21e9c8a34f60",
    "callback_url": "https://hooks.example.com/graine/calls",
    "event_types": ["all_processing_completed"],
    "method_type": "POST",
    "headers": {
      "X-Tenant": "acme-prod",
      "Authorization": "Bearer your-own-endpoint-token"
    },
    "secret": "whsec_2f8c41a09b7e4d6188aa3c5e7b90d412",
    "enabled": true
  }'

{
  "subscription_id": "e0c9a4f2-3b17-4d85-9a6e-2f70c8b1d534",
  "organization_id": "organization-live-4821",
  "agent_id": "agent_5b7d21e9c8a34f60",
  "event_types": ["all_processing_completed"],
  "callback_url": "https://hooks.example.com/graine/calls",
  "method_type": "POST",
  "headers": {
    "X-Tenant": "***",
    "Authorization": "***"
  },
  "secret": "***",
  "has_secret": true,
  "secret_unavailable": false,
  "enabled": true,
  "created_at": "2026-08-27T09:41:22.518Z",
  "updated_at": "2026-08-27T09:41:22.518Z",
  "created_by": "gat_7f3c9a21"
}

Both forms upsert on the natural key (organization_id, agent_id, callback_url), which is a unique index. Re-subscribing the same agent to the same URL updates that subscription; it can never create a twin that double-delivers.

Testing an endpoint

POST /v2/webhooks/test sends one signed event to an endpoint and tells you what came back. Use it instead of placing a call: a test costs nothing, a real call costs a call.

curl -X POST https://api.graine.ai/v2/webhooks/test \
  -H "Authorization: Bearer gat_7f3c9a21b4e85d0c6a19f2734b8e5c60" \
  -H "Content-Type: application/json" \
  -d '{ "subscription_id": "e0c9a4f2-3b17-4d85-9a6e-2f70c8b1d534" }'

Send either callback_url or subscription_id; sending neither is a 400. They differ in what they prove:

You can also pass event_type, agent_id, method_type, headers and secret to override for this test only. Nothing is stored.

The response is 202 — meaning the test was attempted. Read delivered for the outcome. A non-2xx from your endpoint is a successful test with delivered: false, not an error from this API.

{
  "accepted": true,
  "delivered": true,
  "http_status": 200,
  "error_class": null,
  "duration_ms": 214,
  "signed": true,
  "signature_header": "X-Graine-Signature",
  "event_type": "all_processing_completed",
  "event_id": "0d2f1c7a-9e64-4b30-8f52-1a7c6d38e905",
  "delivery_id": "test_9c1e4a7b30d85f26a4c07be1",
  "callback_host": "hooks.example.com",
  "method_type": "POST",
  "sent_header_names": ["Content-Type", "User-Agent", "X-Graine-Signature", "..."],
  "body": { "event_type": "all_processing_completed", "test": true, "...": "..." }
}

What it is and is not:

• It is a test, not a delivery. One attempt, a 10-second budget, no retry ladder. Nothing is written to the delivery ledger — the delivery_id above is synthetic and will not appear in GET /v2/webhooks/deliveries.
• The payload is shaped like a real event — the same envelope keys, the same signature scheme — with synthetic values, no phone number anywhere, and one extra key: "test": true. Drop it on the floor, or use it to route the event away from your production handler.
• signed: false is a finding, not a formality. It means no secret is configured for this subscription or organization, so your signature check can never pass. That is the same state the ledger records as signed: false.
• Your endpoint's response body is deliberately not echoed — only its status code, an error class and the elapsed time.
• The URL is re-checked against its resolved addresses before the request is made, because this endpoint dials on demand from our network. The same target rules as a subscription apply, so a tunnel URL works and localhost does not.

Which subscription receives a call

Subscriptions live at two levels, and they do not union:

1. subscriptions for (your org, this call's agent_id)   ← if ANY enabled one exists, ONLY these are used
2. subscriptions for (your org, no agent)               ← the org-wide fallback
3. the agent's own Custom Webhook URL                   ← set in the dashboard
4. nothing

The dashboard's Custom Webhook

An agent configured under Integrations & Tools → Custom Webhook receives events without any API call, and most existing integrations use exactly this. It behaves as a subscription in every respect:

agent_id in the resolution is the original, pre-A/B-resolution agent id. If the call was served by an A/B variant, routing still follows the agent you dialled.

Propagation

Scope lookups are cached for 60 seconds per process, and the organization's webhook feature flag for 300 seconds. The API runs across several processes, so an edit is effective immediately in the process that served it and within 60 seconds everywhere else. Plan a subscription change one minute ahead of the traffic that depends on it.

Custom headers

Every header you configure is sent on every attempt, after ours. Use them for your endpoint's own authentication, tenant routing, or tracing.

Header names and values are validated on the way in. The stored model would repair each of these silently; /v2 refuses loudly instead, because a header you configured and never see sent is indistinguishable, from a support ticket, from a bug in the delivery engine. Every row below is a 400 on the request that introduced it, and nothing is written:

Header values are encrypted at rest with AES-256-GCM — every value, not a subset guessed to look sensitive — using the same helper that protects stored phone numbers. They are never logged and never returned by the API; the projection shows "***". If a value cannot be decrypted on read, the header is dropped from the delivery rather than sent as ciphertext.

Signing secret

Set secret on the subscription and every delivery carries an X-Graine-Signature header. If the subscription has no secret, your organization's webhook signing secret is used. If neither resolves, deliveries go out unsigned and the delivery record says so.

The full verification recipe, with runnable Node and Python, is in Error handling — Verifying the signature.

Endpoint requirements

Your endpoint must satisfy all of the following, or deliveries fail.

Pausing, deleting, and the organization switch

The organization flag fails open: a missing organization config, a missing flag, or a config we cannot read all mean webhooks are on. The flag exists so an operator can deliberately turn delivery off — a storage hiccup must not do that for every customer at once.

What this engine does not send

Stated plainly so you do not build against something that is not there:

• No replay endpoint. A delivery that exhausts its retries is not re-sendable through the API. Reconstruct from GET /v2/calls/{execution_id}.
• No per-event ordering guarantee. If you subscribe to progress events, a retried call_started can arrive after call_completed. Order by the payload's own fields, never by arrival.
• No inbound-call-only or agent-error event types. The seven above are the complete set.
• No delivery of the raw carrier status string. status and sub_status are always from our own closed vocabulary — see Payloads.

Next