Skip to main content
A webhook is an HTTPS endpoint in your application. Phonovation sends a delivery receipt (DLR) to this endpoint when a message’s delivery status is available. Configure the endpoint URL and signing secret in Phonovation developer settings.

​
Delivery receipt

Phonovation sends a JSON payload with four fields:
Delivered DLR
Treat Status as a string rather than a fixed list of values. Its casing is preserved.

​
Handle the webhook

1

Read the raw body

Keep the exact request body before parsing the JSON. You need those original bytes to verify the signature.
2

Verify the signature

If you configured a signing secret, compare X-Signature with an HMAC-SHA256 digest of the raw body. Reject the request if it does not match.
3

Update your record

Use ClientReference to find the matching record, then save the new Status.
4

Acknowledge the webhook

Return any 2xx response after you have stored or safely queued the event.

​
Signature format

The signature header looks like this:
Signature header
Calculate the HMAC with SHA-256, using your webhook secret as the key and the exact raw UTF-8 body as the input. Compare signatures using a constant-time comparison.
Do not rebuild the JSON before checking the signature. Changes to whitespace or property order will produce a different HMAC.
If no signing secret is configured, X-Signature is omitted. Configure a secret whenever possible.

​
Retries and duplicates

Phonovation retries webhook delivery after these failures:
  • A network failure prevents the HTTP request from completing.
  • Your endpoint returns 404 Not Found.
  • Your endpoint returns 408 Request Timeout.
  • Your endpoint returns a 5xx response.
Other 4xx responses are not retried. This includes 400 Bad Request, 401 Unauthorized, and 403 Forbidden.
A circuit breaker opens for 30 seconds after two transient failures. While it is open, a configured retry may fail fast without making an HTTP request to your endpoint. Because of this, the circuit breaker may prevent all configured retry attempts from becoming actual HTTP requests.
Return a 2xx response only after you have safely stored or queued the event. Retries can deliver the same event more than once, and delivery order is not guaranteed. Make your handler idempotent so processing a duplicate does not repeat a business action or corrupt status.

Webhook API Reference

Review the complete webhook payload and signature contract.