documentation

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):

HeaderMeaning
X-Hail-Signaturet=<unix>,v1=<hex hmac_sha256> — verify this.
X-Hail-EventEvent type, for example email.received.
X-Hail-DeliveryUnique delivery id (stable across retries; use to dedupe).
X-Hail-SubscriptionAlways present — identifies the subscription that produced this delivery.
X-Hail-Email-DomainInformational: 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-types

The 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.reason is one of forward_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_funds can 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 the X-Hail-Email-Domain header.
  • 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_reason no_agent or insufficient_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. data is the call object plus transfer: {"contact_id": "…", "contact_name": "Sam"}. contact_id is the id GET /contacts returns: a contact's uuid, or member:<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."
  }
}
  • data is built by call_summarized_data in call_analysis.py. It has the call.* fields above, plus duration_seconds, transcript and summary.
  • transcript holds the same turns as GET /v1/calls/{id}, in the order they were said. at is when the speaker started the turn. assistant is the agent; user is the other side. Texts the caller sends during the call are not in it (they arrive as sms.received).
  • duration_seconds runs from answer to hang-up. It is null when the call was never answered.
  • summary comes 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-call llm from POST /v1/calls is not used. When the model fails, summary is 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.summarized subscription 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/events shows a summarized call event. It holds counts only (turns, and summary true or false), not the text.
  • Self-hosting: the voicebot sends this event from its text worker, which runs only when HAIL_INTERNAL_SECRET and HAIL_API_URL are 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, END or QUIT. Hail suppresses the sender.
  • START: START, YES or UNSTOP from a sender who opted out. Hail lifts the suppression. From anyone else, these words are a normal reply (null).
  • HELP: HELP or INFO.

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 → 24h

After 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-memory
import { 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.

On this page