Docs / Guides

Webhooks

We push an event to your URL when someone texts your number, each time a message you sent changes status, and when a call ends, is recorded or leaves a voicemail. Every event is signed; verify it before you trust it.

Try it without a server

The dashboard's built-in inbox is a webhook receiver of your own. On Webhooks, choose Use the built-in inbox; events then appear on Events, with their signatures checked the way your receiver should check them.

Create a webhook

Webhooks belong to your account rather than to one API: you manage them in the Account API, and one webhook can receive both message and call events. POST /webhooks, with the webhooks:manage scope — and the scope that reads what each event you subscribe to carries:

curl https://api.phound.app/accounts/v1/webhooks \
  -H "Authorization: Bearer $PHOUND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/phound/webhooks", "events": ["message.*"]}'
Field
urlRequired. Public HTTPS. Addresses on private or internal networks are refused.
eventsRequired. Event types, or message.* / call.* / live_call.* for every message / call event — including ones added later.
failover_urlOptional. Gets one attempt after the primary URL has exhausted its retries.

A webhook is another way to read your data, so the key needs that data's scope too:

EventsScope
message.*, conversation.createdmessages:read
suppression.*, opt_in.createdsuppressions:read
call.completedcalls:read
call.voicemail_*voicemails:read
call.recordedrecordings:read
live_call.*calls:stream

call.* needs calls:read, recordings:read and voicemails:read. Without one, the request is refused with 403 forbidden, naming the event and the scope. The same goes for sending a webhook's events to a new URL, turning it back on, and reading or replaying its delivery log.

The response includes secret (whsec_…). It's returned only this once; afterwards you see its secret_hint. Store it — you need it to verify every event.

A webhook gets the events of all your numbers and your own personas. To send different numbers' or personas' events to different systems, route on the event's persona_id (or from/to).

Change a webhook with PATCH /webhooks/{id} (url, events, failover_url, enabled), and remove it with DELETE /webhooks/{id}.

Events

Messages

From the Messaging API. data is a message.

EventWhen
message.receivedSomeone texted one of your numbers, or replied in the Phound app to a message you sent there.
message.acceptedA message you scheduled (send_at) is waiting to go out.
message.sentA message you sent — through the API or from the Phound app — was accepted by the carrier.
message.deliveredDelivery was confirmed.
message.unconfirmedNo delivery receipt came back within 5 minutes. Usually delivered anyway — not a failure.
message.failedThe carrier reported it undeliverable.
message.rejectedIt was refused, or couldn't be handed to the carrier.
message.editedIts text was changed in the Phound app — however old it is. The event carries the message as it now is, with edited_at.
message.deletedIt was deleted in the Phound app — however old it is. Within a day the API stops returning it, as the app does; within two, once a second check confirms it, this event carries its ids and deleted_at, its content gone, so you can delete your copy.

Messages sent from the Phound app produce events too: sent_via is phound_app on them, api on the API's own, so your code can tell a person's reply from its own sends.

A message you send produces message.sent and then exactly one of the four final events; a scheduled one starts with message.accepted, and can end message.failed (expired) or message.rejected without being sent. See Sending messages for what each status means.

Calls

Calls made and received by you and your own personas, over the Phound app and the phone network — the same calls the Calls API lists. Each happens once, so it carries sequence: 1. data.call_id ties a call's events together; a voicemail's events carry its own id instead.

EventWhendata
call.completedA call ended.The call, as GET /calls/{id} returns it
call.recordedIts recording is ready to download.The recording: url, duration, size
call.voicemail_receivedA caller left a voicemail.The voicemail, as GET /voicemails/{id} returns it
call.voicemail_transcribedThe voicemail's transcription is ready.The same voicemail (same id), with transcription_url set

Streamed calls

Calls streamed to your server — Calls API, Media streams (beta). Each happens once, sequence: 1.

EventWhendata
live_call.answeredThe call was answered; its stream starts.The live call, as GET /live-calls/{id} returns it
live_call.endedThe call ended, answered or not — end_reason says why.The same

New event types can be added; message.*, call.* and live_call.* include them automatically, so ignore any type you don't recognise.

What we send

A POST with a JSON body — the event — and these headers:

content-type: application/json
user-agent: Phound-API-Webhooks/1.0
webhook-id: evt_01m3ae9k2r7t4w6y8z0b1c3d5f
webhook-timestamp: 1790866245
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
{
  "id": "evt_01m3ae9k2r7t4w6y8z0b1c3d5f",
  "object": "event",
  "type": "message.delivered",
  "sequence": 3,
  "occurred_at": "2026-10-01T15:04:21Z",
  "api_version": "v1",
  "owner_id": "1f39a86f-3b0b-8bf3-9a2b-5e90c4f4740c",
  "data": {
    "id": "msg_01m3ae8f0pxc3xn1m8pbdt68gp",
    "object": "message",
    "conversation_id": "conv_01m3ae8f0n5w2q7y1d0x9hcz3k",
    "direction": "outbound",
    "channel": "sms",
    "from": "+13075222720",
    "to": "+14155550123",
    "text": "Your table is ready.",
    "delivery_fidelity": "carrier",
    "status": { "group": "delivered", "state": "delivered_to_carrier", "final": true,
                "description": "Delivered to the recipient's carrier.",
                "occurred_at": "2026-10-01T15:04:21Z", "sequence": 3 },
    "error": null,
    "client_reference": "booking-8812",
    "metadata": {},
    "created_at": "2026-10-01T15:04:05Z"
  }
}

data is the same message object the Messaging API returns from GET /messages/{id}. owner_id is the Phound user the event belongs to — the same id as main_persona.id from the Account API's GET /account. A call event has the same envelope:

{
  "id": "evt_01m3af2c7v9x1z3b5d7f9h1k3m",
  "object": "event",
  "type": "call.completed",
  "sequence": 1,
  "occurred_at": "2026-10-01T15:12:40Z",
  "api_version": "v1",
  "owner_id": "1f39a86f-3b0b-8bf3-9a2b-5e90c4f4740c",
  "data": {
    "id": "call_200acahr5kc2a",
    "object": "call",
    "persona_id": "1f39a86f-3b0b-8bf3-9a2b-5e90c4f4740c",
    "call_id": "4f7d0e6a-2c1b-4e8f-9a3d-7b5c1e0f2a94",
    "direction": "inbound",
    "channel": "pstn",
    "from": "+14155550123",
    "to": "+13075222720",
    "caller_name": "Maria",
    "started_at": "2026-10-01T15:10:40Z",
    "ended_at": "2026-10-01T15:12:40Z",
    "duration": 120
  }
}

Verify the signature

Events are signed per Standard Webhooks, so any Standard Webhooks library works. By hand:

  1. Reject the request if webhook-timestamp is more than 5 minutes from now — it stops replays.
  2. Base64-decode the secret after its whsec_ prefix. That's the HMAC key.
  3. Compute HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw body} and base64-encode it.
  4. webhook-signature is a space-separated list of v1,<signature>. Accept the event if any v1 entry matches, comparing in constant time. There are two during a secret rotation.
Use the raw body

Sign-check the exact bytes you received. Parsing the JSON and serialising it again changes them, and the check fails. In most frameworks that means asking for the raw body on this one route.

import crypto from "node:crypto";
import express from "express";

const secret = process.env.PHOUND_WEBHOOK_SECRET; // whsec_...

function verify(headers, body /* Buffer */) {
  const id = headers["webhook-id"], ts = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = crypto.createHmac("sha256", key)
    .update(`${id}.${ts}.`).update(body).digest();
  return (headers["webhook-signature"] || "").split(" ").some((entry) => {
    const [version, sig] = entry.split(",");
    const got = Buffer.from(sig || "", "base64");
    return version === "v1" && got.length === expected.length && crypto.timingSafeEqual(got, expected);
  });
}

const app = express();
// The raw body, not express.json(): the signature is over the exact bytes.
app.post("/phound/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  if (!verify(req.headers, req.body)) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  // ...queue it for processing, then answer quickly:
  res.sendStatus(204);
});

Answer quickly

Answer 2xx within 10 seconds. Anything else — another status, a timeout, a connection error — counts as a failure and is retried. Redirects aren't followed, so a 3xx is a failure too. Do the real work after you've answered: put the event on a queue, then return 204.

Retries

A failed event is tried again with backoff, up to 10 attempts in all — about three days:

After attempt123456789
Next try in30 s5 min30 min1 h3 h6 h12 h 24 h28 h

Each wait varies by ±10%. Every retry of an event keeps the same webhook-id. If the webhook has a failover_url, it gets one attempt once the primary URL has used all ten.

Automatic disabling

When an event has used every attempt and the webhook hasn't had a successful delivery in 72 hours, the webhook is disabled. Its health.auto_disabled_at says when. While it's disabled, events are still recorded in its delivery log — marked as not attempted — so you can replay what you missed. Turn it back on with PATCH /webhooks/{id} and {"enabled": true}.

Ordering and duplicates

Events can arrive more than once and out of order. Make your handler idempotent:

  • Deduplicate on webhook-id. It's the same on every retry of an event, and equals the event's id.
  • Order by sequence. It goes up with each event about one message. Ignore an event whose sequence isn't higher than the last one you stored for that message. Call events don't need this: each happens once.

Rotate the secret

To replace a secret without dropping events, rotate it with an overlap:

curl -X POST https://api.phound.app/accounts/v1/webhooks/wh_.../rotate-secret \
  -H "Authorization: Bearer $PHOUND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"overlap_seconds": 3600}'

The response carries the new secret, once. Until the overlap ends, every event is signed with both the new and the old secret — two v1 entries in webhook-signature — so receivers with either secret keep working while you deploy the new one. overlap_seconds defaults to 3600 and can be up to 86400; 0 retires the old secret at once.

Test events

Check your endpoint before anything real happens:

curl -X POST https://api.phound.app/accounts/v1/webhooks/wh_.../test \
  -H "Authorization: Bearer $PHOUND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "message.received"}'

Any event type can be tested. A test event is delivered right away, outside the retry schedule, and signed like a real one. Its data is a realistic message, call, recording or voicemail with "test": true — a message's id is msg_test — so make sure your handler doesn't act on it. The response is the attempt itself: the request we sent, your endpoint's status, headers and body, and how long it took.

The delivery log

Every attempt is kept for 30 days, with exactly what was sent and what your endpoint answered.

Request
GET /webhooks/{id}/deliveriesAttempts, newest first. Filter with succeeded=false, event, resource_id (a message or call id) or since; page with limit (up to 100) and cursor.
POST /webhook-deliveries/{id}/retrySend that attempt's event again, now, to the webhook's current URL.

A replay's body is the event exactly as it was, but it gets a new webhook-id, so your deduplication doesn't drop it. The event's id in the body stays the original's.

The dashboard shows the same log under each webhook's Delivery log.