What happens when your callback is down
Terminal outcomes are pushed to a URL you control, with a small bounded retry. Your handler has to tolerate a repeat, and it should not expect a call for every message.
Read the guide →Push receipts to your own endpoint
Polling for status works until the volume makes it wasteful. A callback lets the system that cares about an event be told about it, which also means the record lands in your own database at the same time.
How it is configured
A callback endpoint is set per tenant, and the platform pushes receipt events to it as they are normalised. The destination is yours, so the event can be recorded, acted on, or fanned out internally without asking the platform again.
- Endpoint configured per tenant
- Receipt events pushed rather than polled
- The event record also lives in your own system
How callback delivery behaves
A webhook is not a database write. Endpoints go down, deployments return errors, and a push can be lost — so design the handler to be idempotent and reconcile against the message log, which is the authoritative record.
- Make the handler idempotent — the same event may arrive more than once
- Reconcile against the logs rather than assuming every push arrived
- Treat the callback as a fast path, not as your system of record
What the events carry
The events pushed are the ones the platform produces — normalised delivery receipts from the SMS channel, so your endpoint receives one stable status rather than a provider-specific word it has to interpret.
Questions this usually raises
- How many times will a callback be retried?
- Treat the callback as best-effort: make the handler idempotent and reconcile against the message log, which is your record of truth. The callback guide sets out the model.
- Can I have more than one endpoint?
- The callback destination is configured per tenant. Fan-out to several internal consumers is something your own endpoint can do once it receives the event.
- Do webhooks cover email and WhatsApp?
- The events described here come from the SMS receipt pipeline. Email and WhatsApp events arrive through their own channel pipelines.
Keep reading
Reading a delivery receipt
A receipt is a sequence of states, not a verdict. Treating an intermediate one as final is the most common way a sending dashboard ends up lying to you.
Read the guide →Bring-your-own provider connections
You keep the provider relationship you already have, connect it once, and the platform treats that account as a send path it can route through, pace against and read receipts from.
Open →Routing and automatic failover
One provider account is a single point of failure that you cannot see failing until customers tell you. Routing across several accounts turns that into a failover you configure once.
Open →Normalised delivery receipts
Two providers describe the same outcome with two different words, and neither word means what the reader assumes. Normalising receipts into one status is what makes a receipt usable in code rather than as a screenshot.
Open →Opt-out and suppression
Suppression is the part of messaging that is easy to get almost right and expensive to get wrong: honour it too broadly and confirmations stop arriving; honour it too narrowly and you are ignoring a customer who asked you to stop. Getting it right is the whole feature.
Open →Pacing at the provider’s real limit
The limit that stops your traffic is not your application’s quota — it is the rate your provider applies per sender number. One number, one limit, and a batch that ignores it fails partway through.
Open →Sender identity you own
The sender is the first thing a recipient sees and the thing that decides whether a message is trusted. Because that identity sits on your own account, it stays with you however you choose to send.
Open →Send API
Product messaging is emitted by code, not typed by a person. The API exists so the service that knows an event happened is the service that sends the message about it.
Open →Message logs and usage
The first question after any messaging incident is “what did we actually send?”. That answer should come from a log with a filter on it, not from a reconstruction.
Open →Tenant isolation
Isolation is the feature that nobody asks about until it is missing. Holding connections, keys and records per tenant means a shared platform does not become a shared inbox.
Open →Manual sending from the console
Not every message comes from an API. Testing a new sender, resending after a fix, or simply looking up what a customer received — those are console jobs, and they should not require writing code.
Open →Scope. Whaleal Messaging is an orchestration layer over the CPaaS or BSP accounts you already hold. Your contracts, your rates and your sender identities stay yours, and nothing in the middle reprices them. Each page states the channel a capability ships on, so you can plan against what is available today.