Webhook Retries, Timeouts & Delivery Status

Project Blue webhooks are single-attempt today. This article covers what that means in practice and how to detect delivery failures without a dedicated failure webhook.

No automatic retries

Webhook delivery is fire-and-forget: we make one HTTPS POST to your configured URL. If your endpoint is down, times out, or returns an error, we do not retry and do not queue the event for later delivery.

There's no signature or HMAC header on the request — authentication is via a secret you include in your webhook URL.
Design your endpoint to respond quickly, ideally within about 10 seconds.

Because there's no retry or replay today, treat webhook delivery as best-effort. Any workflow where a missed event would be costly should be backed up by polling (see below), not by the webhook alone. We're aware this is a gap and have retries, a delivery log, and manual replay on our roadmap.

Checking delivery and failure status

There is currently no dedicated delivery, failure, or read-receipt webhook — webhook events cover message content going in and out, not status changes after the fact. To check on a message's outcome:

Call GET /get-messages-api for the message.
Check the status field: pending means still queued, delivered means it went out (sent_at will be set).
A message stuck in pending for longer than expected is your signal something went wrong.

Immediate, same-call failures (for example, a malformed number) come back as a 4xx/5xx response from the send endpoint itself — handle those synchronously in your send code.

Recommended pattern for API-only integrations

If you're running your own timing/orchestration on the API, we recommend:

Use the webhook as a fast-path notification, not your only source of truth.
Periodically poll /get-messages-api for any sends still pending past a reasonable window, and treat those as needing follow-up.
Log webhook receipt on your end so you can spot gaps if an event is ever missed.