Webhooks
When a subscribed event occurs — inbound mail or SMS, a delivery report, a
call outcome — Hail POSTs a signed JSON event to your URL. Verify the
X-Hail-Signature header against the once-shown secret. Return any 2xx,
and you are done. Hail retries a non-2xx response (or a timeout) on a fixed
ladder.
Verify the signature (Python)
The signature is HMAC-SHA256 over f"{t}.{body}" — the timestamp from the
header, a literal ., then the raw request bytes. This is a runnable
example. The assert passes (the real signer in
core/hailhq/core/webhooks.py produced
the fixture):
import hashlib, hmac
def verify(secret: str, signature_header: str, raw_body: bytes) -> bool:
# signature_header looks like "t=1700000000,v1=<hex>"
parts = dict(p.split("=", 1) for p in signature_header.split(","))
t, v1 = parts["t"], parts["v1"]
mac = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256)
return hmac.compare_digest(mac.hexdigest(), v1)
# Worked example — prints True:
assert verify(
"whsec_example",
"t=1700000000,v1=72f7940d13ca8528cf655a04e82dabfe90a531e239241fda9bdff72980d33a4a",
b'{"id":"evt_123","type":"email.received","data":{"id":"em_1"}}',
)Verify the signature (Node)
Hash the raw request body bytes, not a re-serialized object — JSON key order and whitespace would differ and the HMAC would not match.
import crypto from "node:crypto";
function verify(secret, signatureHeader, rawBody) {
// rawBody is a Buffer of the exact bytes Hail sent.
const parts = Object.fromEntries(
signatureHeader.split(",").map((p) => p.split(/=(.*)/s).slice(0, 2)),
);
const mac = crypto
.createHmac("sha256", secret)
.update(`${parts.t}.`)
.update(rawBody)
.digest("hex");
return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(parts.v1));
}In Express, capture the raw bytes with express.raw({ type: "application/json" }).
In Next.js route handlers, use await req.text() / req.arrayBuffer() and pass
those bytes, not await req.json().
Headers
Every delivery carries these headers (refer to
core/hailhq/core/webhook_worker.py):
| Header | Meaning |
|---|---|
X-Hail-Signature | t=<unix>,v1=<hex hmac_sha256> — verify this. |
X-Hail-Event | Event type, for example email.received. |
X-Hail-Delivery | Unique delivery id (stable across retries; use to dedupe). |
X-Hail-Subscription | Always present — identifies the subscription that produced this delivery. |
X-Hail-Email-Domain | Informational: the source email domain for inbound events (when known). Branch on this to route per-domain in your handler. |
Event types
Read supported event names, labels, and channels from the public catalog:
curl https://api.hail.so/v1/webhooks/event-typesThe response contains an items array. Use each item's type in a subscription's event_types.
This endpoint needs no API key. Creating or changing a subscription still requires authentication.
The catalog and subscription validation share the WebhookEventType registry in
core/hailhq/core/webhook_events.py:
email.received— a message arrived, and Hail accepted it.email.received.suppressed— a message arrived, but Hail held back fan-out/forwarding.data.reasonis one offorward_loop,forward_rate_limit,inbound_rate_limit,insufficient_funds. One event fires per reason (a single message can produce more than one suppressed event).insufficient_fundscan also fire later, when a queued forward is about to be sent and the balance has run out.email.delivered— SES accepted the message for delivery.email.delivery_delayed— SES reports a transient delay.email.bounced— the recipient mail server rejected the message (permanent or soft bounce).email.complained— the recipient marked the message as spam.email.opened— the recipient opened the message (image tracked, approximate). Only fires for emails sent with an HTML body; plain-text-only emails are never tracked for opens.email.clicked— the recipient clicked a tracked link. Only fires for emails sent with an HTML body; plain-text-only emails are never tracked for clicks.email.send_failed— an outbound email failed to send.sms.received— an inbound SMS arrived, and Hail accepted it. Hail delivers it through the same signed, retried webhook worker as the email events (X-Hail-Signature,X-Hail-Event,X-Hail-Delivery). Hail omits theX-Hail-Email-Domainheader.sms.delivered— the carrier confirmed delivery (requires Twilio delivery receipts).sms.undelivered— the carrier reported the message was not delivered.sms.failed— the send failed (transport error or carrier rejection).
Call lifecycle — received (inbound only), answered, completed,
failed, busy, no_answer, transferred, summarized (there is no canceled event; it has no data source):
call.received— an inbound call reached one of your numbers and an agent is about to answer (Agents). Fired before the answer.call.answered— the other side is on the line (call entered in-progress).call.completed— the call ended normally.call.failed— the call failed (setup error, trunk/media failure, force-closed, or an inbound call Hail refused:end_reasonno_agentorinsufficient_funds).call.busy— the callee was busy or rejected the call.call.no_answer— the callee did not answer.call.transferred— the agent handed the live call to a person (Agents). Sent once, when someone on that person's line has spoken and stayed on for 10 seconds.datais the call object plustransfer:{"contact_id": "…", "contact_name": "Sam"}.contact_idis the idGET /contactsreturns: a contact's uuid, ormember:<user id>for a team member. Never a phone number.call.summarized— the call's transcript and a short AI summary, sent once after the call ends (Call summarized).
Every call.* payload's data carries id, status, direction
(inbound or outbound), from, to, agent_id (null for calls placed
with an inline prompt) and, once terminal, end_reason
(call_event_data):
Failed call responses and call.failed events also carry failure_message.
For a confirmed geographic-permission block, it explains that calling the
destination is disabled. Raw carrier error text is never returned.
{
"type": "call.received",
"data": {
"id": "0d9c…",
"status": "ringing",
"direction": "inbound",
"from": "+33612345678",
"to": "+14155550100",
"agent_id": "a1b2…"
}
}Call summarized
Subscribe to call.summarized to get what was said on each call and a short
summary, about 10 seconds after the call ends:
curl -X POST "$HAIL_API_URL/v1/webhooks" \
-H "Authorization: Bearer $HAIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"target_url": "https://example.com/hooks/hail", "event_types": ["call.summarized"]}'{
"type": "call.summarized",
"data": {
"id": "0d9c…",
"status": "completed",
"direction": "inbound",
"from": "+33612345678",
"to": "+14155550100",
"agent_id": "a1b2…",
"end_reason": "normal_hangup",
"duration_seconds": 74,
"transcript": [
{
"role": "assistant",
"text": "Hi, this is an AI assistant answering on behalf of Acme.",
"at": "2026-11-17T12:00:02Z"
},
{
"role": "user",
"text": "Hi, I'd like to move my Tuesday appointment.",
"at": "2026-11-17T12:00:06Z"
}
],
"summary": "The caller asked to move their Tuesday appointment. The agent moved it to Thursday at 10am."
}
}datais built bycall_summarized_dataincall_analysis.py. It has thecall.*fields above, plusduration_seconds,transcriptandsummary.transcriptholds the same turns asGET /v1/calls/{id}, in the order they were said.atis when the speaker started the turn.assistantis the agent;useris the other side. Texts the caller sends during the call are not in it (they arrive assms.received).duration_secondsruns from answer to hang-up. It is null when the call was never answered.summarycomes from your workspace's own LLM when you set one (Hail's models back it up only when you turned fallback on). Otherwise it comes from Hail's chain, the one calls and texts use (Anthropic, then OpenAI, then Gemini). A per-callllmfromPOST /v1/callsis not used. When the model fails,summaryis null and the event is still sent.- Only phone calls with at least one spoken turn are sent. A call nobody spoke on gets no event.
- Only calls that end after your
call.summarizedsubscription was created or last changed (PATCH, secret rotation) are sent, so turning it on never replays past calls. A call not sent within 24 hours of its end is dropped. - Once it is sent,
GET /v1/eventsshows asummarizedcall event. It holds counts only (turns, andsummarytrue or false), not the text. - Self-hosting: the voicebot sends this event from its text worker, which
runs only when
HAIL_INTERNAL_SECRETandHAIL_API_URLare set.
Payload
Hail wraps every event in this envelope (build_event_payload in
webhooks.py assembles it). The data
shape comes from the event type. Inbound events use build_event_data for email.received*. Delivery events use build_delivery_event_data for the lifecycle events.
Inbound example (email.received):
{
"id": "9f2c…",
"type": "email.received",
"api_version": "2026-06-06",
"created_at": "2026-06-14T12:00:00+00:00",
"organization_id": "org-uuid",
"data": {
"id": "em-uuid",
"direction": "inbound",
"from_address": "sender@example.com",
"to_addresses": ["agent@yourorg.hail.so"],
"subject": "Re: invoice",
"message_id": "<abc@example.com>",
"in_reply_to": "<def@yourorg.hail.so>",
"spam_verdict": "PASS",
"virus_verdict": "PASS",
"spf_verdict": "PASS",
"dkim_verdict": "PASS",
"dmarc_verdict": "PASS",
"raw_url": "https://api.hail.so/v1/emails/em-uuid/raw",
"attachments": [
{
"id": "att-uuid",
"filename": "invoice.pdf",
"content_type": "application/pdf",
"size_bytes": 12345,
"url": "https://…"
}
]
}
}Inbound example (sms.received):
{
"id": "7a1b…",
"type": "sms.received",
"api_version": "2026-06-06",
"created_at": "2026-07-10T12:00:00+00:00",
"organization_id": "org-uuid",
"data": {
"id": "sms-uuid",
"from": "+14155551234",
"to": "+14155559999",
"body": "hello back",
"compliance_keyword": null
}
}compliance_keyword is "STOP", "START" or "HELP" when the text is one of
these keywords, and null otherwise. The same value is in the received event
on GET /v1/events (events stored before this field existed do not have it).
STOP:STOP,STOPALL,UNSUBSCRIBE,CANCEL,ENDorQUIT. Hail suppresses the sender.START:START,YESorUNSTOPfrom a sender who opted out. Hail lifts the suppression. From anyone else, these words are a normal reply (null).HELP:HELPorINFO.
Matching ignores case and surrounding spaces. When Twilio sends its own opt-out
type for a text, that type decides too (sms_ingest.py).
The carrier or Hail answers these keywords, depending on your setup, so a bot
should not answer them too.
raw_url and each attachment url are Hail API endpoints that 302-redirect to a
presigned S3 URL on access. email.received.suppressed carries a trimmed data
(id, direction, from_address, to_addresses, subject, message_id,
reason) — no verdicts, raw_url, or attachments.
Outbound delivery example (email.bounced):
{
"id": "9f2c…",
"type": "email.bounced",
"api_version": "2026-06-06",
"created_at": "2026-07-02T12:00:05+00:00",
"organization_id": "org-uuid",
"data": {
"id": "em-uuid",
"kind": "bounced",
"occurred_at": "2026-07-01T12:00:05+00:00",
"from_address": "noreply@acme.com",
"to_addresses": ["bob@example.com"],
"subject": "Welcome",
"detail": {
"hard": true,
"bounce_type": "Permanent",
"bounce_sub_type": "General",
"recipients": ["bob@example.com"],
"diagnostic_code": "smtp; 550 5.1.1 user unknown"
}
}
}The detail field varies by event type. bounced and complained carry SES metadata. delivered and delivery_delayed carry SES status details. opened and clicked carry ip_address and user_agent; clicked adds link (the event time is the sibling occurred_at field). Both only occur for emails sent with an HTML body: the tracking pixel and link rewriting live in the HTML part, so plain-text-only emails never produce them. For bounced, the provider-neutral hard flag distinguishes hard bounces from soft bounces. Only hard bounces move the email to status=bounced and count toward bounced_hard in GET /emails/stats.
Retries
Hail retries a delivery that does not get a 2xx on this fixed ladder
(RETRY_SCHEDULE_SECONDS in webhooks.py):
0s → 30s → 2m → 10m → 1h → 6h → 24hAfter the 7th attempt fails, Hail marks the delivery dead. When an org-wide
subscription accrues 50 consecutive dead deliveries, it auto-disables. To
re-enable it, set its status back to active. Replay a single delivery from the
console or through the API:
curl -X POST "$HAIL_API_URL/v1/webhooks/<subscription-id>/deliveries/<delivery-id>/redeliver" \
-H "Authorization: Bearer $HAIL_API_KEY"Subscribe
Create a subscription. The response returns the signing secret once, at create:
POST /webhooks {"target_url": "https://example.com/hooks/hail",
"event_types": ["email.received", "email.received.suppressed"]}The event_types enum and request/response schemas are in
openapi/openapi.yaml (WebhookSubscriptionCreate).
The CLI has no webhooks command group — for the full endpoint list, refer to
the CLI reference.
Chat SDK
The published Hail adapter connects SMS to a Vercel Chat SDK bot. Hail also supports email and phone calls through its APIs; this adapter currently exposes SMS.
Install the adapter and a Chat SDK state backend:
pnpm add @hail-hq/chat-sdk-adapter chat @chat-adapter/state-memoryimport { Chat } from "chat";
import { createMemoryState } from "@chat-adapter/state-memory";
import { createHailAdapter } from "@hail-hq/chat-sdk-adapter";
export const bot = new Chat({
userName: "mybot",
adapters: { hail: createHailAdapter() },
state: createMemoryState(),
});
bot.onDirectMessage(async (thread, message) => {
await thread.post(`You said: ${message.text}`);
});Set HAIL_API_KEY, HAIL_FROM_NUMBER (your Hail-owned E.164 number), and
HAIL_WEBHOOK_SECRET. Subscribe to sms.received and route the webhook to
bot.webhooks.hail(request). Set HAIL_RECIPIENT_CONSENT=true only when you
attest to the required consent for all recipients; otherwise sending fails.
Clear the number's sms_agent_id if a Hail text agent would also answer it.
Memory state needs no external database. Use a shared state adapter, such as Redis or PostgreSQL, for multiple instances or serverless deployments; Redis is not a Hail requirement.
The adapter verifies signatures, isolates conversations by phone pair, and
supports SMS replies. It requires Node.js 20+ and chat >=4.44.0.
Refer to the adapter setup, configuration, and limitations
and its Next.js example.
See the 0.1.0 release announcement for the published package and supported capabilities. Hail maintains the adapter; a Vercel vendor-official listing requires separate acceptance.