Webhooks

Receive real-time events from Allison at an https:// endpoint you control. No polling, no delay.

What they're for

Calls finish, callbacks get requested, appointments get booked. Webhooks push those events to your service the moment they happen — useful for syncing a CRM, notifying a Slack channel, kicking off a follow-up automation, or storing call history in your own warehouse.

Every subscription is scoped to your organization. You control which events to receive, the URL they're sent to, and when to enable or disable delivery. Secrets are rotated by you, never shared between subscriptions.

The delivery contract

HTTP POST with Content-Type: application/json. The body is a versioned envelope with an id, type, created_at, and data.
Signed — every request carries an X-Allison-Signature header. See the signing guide.
Retried on anything other than 2xx. Up to six attempts over ~32 hours. See retry & idempotency.
Timeout: 10 seconds. If your receiver doesn't respond in 10 seconds we treat it as a failure and schedule a retry.
No redirects. We POST directly to the URL you registered — 3xx responses are treated as failures.

Set up a subscription

Admins can register a subscription from the dashboard (Settings → Webhooks) or via the API. Creating a subscription returns a one-time secret — save it immediately; we cannot show it again.

curl https://api.allisonvoice.com/v1/webhook-subscriptions \
  -H "Authorization: Bearer av_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks/allison",
    "events": ["call.ended", "call.callback_requested"]
  }'

Response:

{
  "data": {
    "id": "c1a5…",
    "url": "https://your-app.example.com/webhooks/allison",
    "events": ["call.ended", "call.callback_requested"],
    "secret_preview": "whsec_ABC12345...",
    "enabled": true,
    ...
  },
  "secret": "whsec_ABC12345XYZ...",
  "warning": "This secret will not be shown again..."
}

The secret field is returned exactly once. Subsequent reads return secret_preview (first 8 characters) only. If you lose the secret, rotate it — rotation replaces the secret atomically.

Receiver checklist

Serve on https:// — http is rejected at registration time.
Respond with any 2xx status as soon as you've durably recorded the event. Don't wait for downstream processing — enqueue and return.
Verify the signature on every request. Reject unsigned or mismatched requests with 401.
Dedupe on event.id — retries reuse the same id, so it's safe to ignore an event you've already processed.
Reject stale requests — the X-Allison-Timestamp header should be within ~5 minutes of now. This prevents replay of captured traffic.
If you permanently retire an endpoint, return 410 Gone — we'll auto-disable the subscription and stop sending.

Event catalog

Six event types are available today. Each has a stable payload shape documented in the events reference.

call.ended

Fires after every customer call completes. Includes transcript, summary, and outcome.

call.callback_requested

Caller asked for a human callback during the call.

call.message_taken

Caller left a message for a specific team member.

call.escalation_triggered

An escalation rule matched and the call was routed out.

call.appointment_booked

A booking was created during the call.

contact.created

A new caller contact was auto-created from a call.

Next steps

Signing — how to verify X-Allison-Signature
Events — payload shape for every event type
Retry & idempotency — retry schedule, auto-disable, and how to dedupe
API Reference — subscription CRUD endpoints under /v1/webhook-subscriptions