Developers
Messaging Webhook Integration & Delivery Reports
A messaging webhook is an HTTPS endpoint on your server that receives automatic notifications from a messaging platform, such as SMS delivery reports, RCS and WhatsApp read and reply events, and voice call outcomes, so your CRM or application stays up to date without repeatedly asking for status.
What is a messaging webhook?
A messaging webhook is an HTTPS endpoint, also called a callback URL, that you host and register with a messaging platform. Whenever something happens to a message you sent (it is delivered, read or fails), or a customer responds, the platform sends an HTTP POST describing the event to that URL. Your application receives the update within moments instead of having to ask for it.
For a business, that means an OTP screen can show “code delivered”, a CRM can flag numbers that keep failing, and a support team can see WhatsApp or RCS replies as they arrive.
How webhook callbacks work
- Your application sends a message through the API and stores the message ID it receives.
- The messaging platform (operator, RCS platform, WhatsApp or voice network) handles delivery.
- Each status change or customer interaction is recorded as an event that references the message ID.
- The event is posted to your callback URL as JSON over HTTPS.
- Your endpoint verifies and records the event, responds with a 2xx status, and updates your application in the background.
Step 1
Customer sends API request
Your system submits a message and stores the returned message ID.
Step 2
Messaging platform
The operator, RCS platform, WhatsApp or voice network handles delivery.
Step 3
Status / event
A delivery status or customer interaction is recorded for the message.
Step 4
Webhook callback
The event is sent as an HTTPS POST to your callback URL.
Step 5
Customer application
Your CRM or application matches the message ID and updates the record.
Webhook vs API polling
| Webhook (push) | API polling (pull) | |
|---|---|---|
| How it works | The platform sends an HTTPS POST to your callback URL when an event happens. | Your system asks the API for the status of each message on a schedule. |
| Freshness | Near real time, as events are recorded. | Only as fresh as your polling interval. |
| Load | One request per event. | Many requests, most returning “no change”. |
| You must build | A public HTTPS endpoint with verification, deduplication and monitoring. | A scheduler, rate-limit handling and status reconciliation. |
| Best for | Delivery reports, replies, read events and call outcomes at volume. | Low volumes, or reconciling events missed during an outage. |
Many teams use both: webhooks for real-time updates and a periodic status check, where the API supports it, to reconcile anything missed.
By channel
Webhooks by messaging channel
Each channel reports different events. These guides explain what each one sends and how to handle it.
SMS delivery report (DLR) webhooks
Delivery statuses, operator error codes, message ID mapping and CRM updates for SMS.
Read the guideRCS Business Messaging webhooks
Delivered, read, reply and suggestion events from your verified agent, and engagement reporting.
Read the guideWhatsApp Business API webhooks
Meta’s webhook model: incoming messages, status updates, verification and signatures.
Read the guideVoice call webhooks
Call progress and outcomes, duration and IVR keypresses for OBD, IVR and voice OTP.
Read the guide
Delivery reports and event notifications
A delivery event usually carries a small set of identifiers and a status. The example below shows the shape such an event can take, so you can plan your database fields and processing logic.
{
"event_id": "evt_example_001",
"event_type": "message.delivered",
"message_id": "msg_example_123",
"channel": "sms",
"status": "DELIVERED",
"timestamp": "2026-11-08T10:30:00Z"
}| Field | Type | What it is for |
|---|---|---|
event_id | String | Identifies this notification. If the same event is delivered twice, the event ID is identical, so it is the key for deduplication. |
event_type | String | Names what happened, for example a delivery, read, failure or reply. Route processing on this value. |
message_id | String | The ID returned when the message was submitted. It links the event to the record in your system. |
channel | String | The channel the event belongs to: sms, rcs, whatsapp or voice. |
status | String | The status the event reports, for example DELIVERED or FAILED. |
timestamp | String (ISO 8601, UTC) | When the platform recorded the event, which is not necessarily when it reached you. Use it to order events. |
Event names, status values, field names, authentication and retry behaviour depend on the provider API specification for your account. TXTPro confirms the exact format, callback registration and any allowlisting steps during onboarding.
Setup
Configuring a webhook endpoint
Ten steps from an empty route to a monitored production integration. Callback registration and allowlisting procedures require confirmation for your account during onboarding.
- 01
Create an HTTPS endpoint
Build a route on your server that accepts POST requests with a JSON body over HTTPS.
- 02
Share the callback URL
Provide the endpoint URL to TXTPro for the channels and events you want to receive.
- 03
Configuration and allowlisting
TXTPro configures the callback, and any allowlisting, where applicable. The registration and allowlisting procedure is confirmed during onboarding.
- 04
Receive events
Your endpoint receives status and interaction events as they happen.
- 05
Verify authenticity
Check the signature or other authentication method confirmed for your account before trusting the payload.
- 06
Validate the payload
Check required fields, types and allowed values; reject anything that does not match.
- 07
Store idempotently
Record the event ID first so a retried or duplicated event is processed only once.
- 08
Update message status
Match the message ID to your record and update its status, respecting event order.
- 09
Acknowledge quickly
Return a 2xx response once the event is safely queued, and do slower work asynchronously.
- 10
Monitor and alert
Track failures, latency and queue depth, and alert when events stop arriving or start failing.
Recommended webhook tooling to plan for
These are recommendations for mature webhook integrations, described for planning purposes. They are not current TXTPro features.
- Webhook event dashboard. A view of recent events per channel, with status and response codes for each delivery attempt.
- Delivery logs. Searchable logs of webhook attempts, response times and errors, with personal data masked.
- Event replay. Re-send selected events after an outage, using the original event IDs so deduplication still works.
- Webhook test tool. Send a sample event to a test URL to check verification and parsing before going live.
- Endpoint health monitoring. Alerts when your endpoint returns errors, times out or stops acknowledging events.
Authentication and security
A callback URL is public, so never trust a request just because it reached it. The essentials:
- Accept events only over HTTPS with a valid certificate.
- Authenticate every request with the method confirmed for your account, for example a signature over the raw body, compared in constant time.
- Deduplicate on event ID, cap request sizes and rate-limit the endpoint.
- Log identifiers only: never phone numbers, message text, OTPs or secrets.
Signing, retry behaviour and allowlisting for TXTPro callbacks require confirmation during onboarding. The webhook security best practices guide explains HMAC signatures, replay protection, secret rotation, queues and monitoring.
Code
Node.js and Python integration examples
Complete receivers you can run locally. Both use a clearly labelled generic HMAC scheme and refuse to start without signing configuration.
FAQs
Webhook FAQs
Can’t find your answer? Contact our team.
What is a webhook in business messaging?
A webhook is an HTTPS endpoint on your server that receives automatic notifications, such as delivery reports, read events, replies or call outcomes, as soon as they happen, instead of your system repeatedly asking for status.
Does TXTPro support webhooks for delivery reports?
Delivery and interaction events can be reported back to your systems. The available mechanism for your account (webhook callbacks or status retrieval), the event format and the callback registration steps are confirmed during onboarding.
Is there a public TXTPro webhook schema?
No public schema is published on this website. The sample payloads shown here are illustrative. The exact fields, status values and authentication method are shared with customers during onboarding.
Why might my endpoint receive the same event twice?
Senders retry when an endpoint times out or returns an error, so the same event can arrive more than once. Store each event ID and ignore events you have already processed.
What should my webhook endpoint return?
Return a 2xx status once the event is verified and safely queued, and do slower processing asynchronously. Return 4xx for invalid or unauthenticated requests. A 5xx response or a timeout usually causes the sender to retry, where retries are supported.
Get integration support
Tell us which channels and events you need and where they should go. Our team will explain the integration options for your account and share the technical documentation during onboarding.
Prefer to call? +91 90304 02858 · Email info@txtpro.in
