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.
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 | |
|---|---|
url | Required. Public HTTPS. Addresses on private or internal networks are refused. |
events | Required. Event types, or message.* / call.* / live_call.* for
every message / call event — including ones added later. |
failover_url | Optional. 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:
| Events | Scope |
|---|---|
message.*, conversation.created | messages:read |
suppression.*, opt_in.created | suppressions:read |
call.completed | calls:read |
call.voicemail_* | voicemails:read |
call.recorded | recordings: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.
| Event | When |
|---|---|
message.received | Someone texted one of your numbers, or replied in the Phound app to a message you sent there. |
message.accepted | A message you scheduled (send_at) is waiting to go
out. |
message.sent | A message you sent — through the API or from the Phound app — was accepted by the carrier. |
message.delivered | Delivery was confirmed. |
message.unconfirmed | No delivery receipt came back within 5 minutes. Usually delivered anyway — not a failure. |
message.failed | The carrier reported it undeliverable. |
message.rejected | It was refused, or couldn't be handed to the carrier. |
message.edited | Its text was changed in the Phound app — however old it is. The event
carries the message as it now is, with edited_at. |
message.deleted | It 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.
| Event | When | data |
|---|---|---|
call.completed | A call ended. | The call, as GET /calls/{id}
returns it |
call.recorded | Its recording is ready to download. | The recording:
url, duration, size |
call.voicemail_received | A caller left a voicemail. | The voicemail, as
GET /voicemails/{id} returns it |
call.voicemail_transcribed | The 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.
| Event | When | data |
|---|---|---|
live_call.answered | The call was answered; its stream starts. | The live call, as
GET /live-calls/{id} returns it |
live_call.ended | The 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:
- Reject the request if
webhook-timestampis more than 5 minutes from now — it stops replays. - Base64-decode the secret after its
whsec_prefix. That's the HMAC key. - Compute HMAC-SHA256 over
{webhook-id}.{webhook-timestamp}.{raw body}and base64-encode it. webhook-signatureis a space-separated list ofv1,<signature>. Accept the event if anyv1entry matches, comparing in constant time. There are two during a secret rotation.
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);
});
import base64, hashlib, hmac, os, time
from flask import Flask, request
SECRET = os.environ["PHOUND_WEBHOOK_SECRET"] # whsec_...
def verify(headers, body: bytes) -> bool:
msg_id, ts = headers["webhook-id"], headers["webhook-timestamp"]
if abs(time.time() - int(ts)) > 300:
return False
key = base64.b64decode(SECRET.removeprefix("whsec_"))
signed = f"{msg_id}.{ts}.".encode() + body
expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
return any(
hmac.compare_digest(sig, expected)
for version, _, sig in (s.partition(",") for s in headers.get("webhook-signature", "").split())
if version == "v1"
)
app = Flask(__name__)
@app.post("/phound/webhooks")
def webhook():
body = request.get_data() # raw bytes
if not verify(request.headers, body):
return "", 400
event = request.get_json()
# ...queue it for processing, then answer quickly:
return "", 204
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/base64"
"fmt"
"io"
"net/http"
"os"
"strconv"
"strings"
"time"
)
func verify(secret string, h http.Header, body []byte) bool {
id, ts := h.Get("webhook-id"), h.Get("webhook-timestamp")
sec, err := strconv.ParseInt(ts, 10, 64)
if err != nil || time.Since(time.Unix(sec, 0)).Abs() > 5*time.Minute {
return false
}
key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
if err != nil {
return false
}
mac := hmac.New(sha256.New, key)
fmt.Fprintf(mac, "%s.%s.", id, ts)
mac.Write(body)
expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))
for _, entry := range strings.Fields(h.Get("webhook-signature")) {
version, sig, _ := strings.Cut(entry, ",")
if version == "v1" && hmac.Equal([]byte(sig), []byte(expected)) {
return true
}
}
return false
}
func main() {
secret := os.Getenv("PHOUND_WEBHOOK_SECRET") // whsec_...
http.HandleFunc("POST /phound/webhooks", func(w http.ResponseWriter, r *http.Request) {
body, _ := io.ReadAll(io.LimitReader(r.Body, 1<<20))
if !verify(secret, r.Header, body) {
w.WriteHeader(http.StatusBadRequest)
return
}
// ...queue the event for processing, then answer quickly:
w.WriteHeader(http.StatusNoContent)
})
http.ListenAndServe(":8080", nil)
}
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 attempt | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
|---|---|---|---|---|---|---|---|---|---|
| Next try in | 30 s | 5 min | 30 min | 1 h | 3 h | 6 h | 12 h | 24 h | 28 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'sid. - Order by
sequence. It goes up with each event about one message. Ignore an event whosesequenceisn'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}/deliveries | Attempts, 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}/retry | Send 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.