Skip to content
TXTPro

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

  1. Your application sends a message through the API and stores the message ID it receives.
  2. The messaging platform (operator, RCS platform, WhatsApp or voice network) handles delivery.
  3. Each status change or customer interaction is recorded as an event that references the message ID.
  4. The event is posted to your callback URL as JSON over HTTPS.
  5. Your endpoint verifies and records the event, responds with a 2xx status, and updates your application in the background.
  1. Step 1

    Customer sends API request

    Your system submits a message and stores the returned message ID.

  2. Step 2

    Messaging platform

    The operator, RCS platform, WhatsApp or voice network handles delivery.

  3. Step 3

    Status / event

    A delivery status or customer interaction is recorded for the message.

  4. Step 4

    Webhook callback

    The event is sent as an HTTPS POST to your callback URL.

  5. Step 5

    Customer application

    Your CRM or application matches the message ID and updates the record.

Conceptual flow, not a confirmed system architecture. The actual path, event names and timing depend on the channel and the provider API specification for your account.

Webhook vs API polling

Comparing webhooks and polling for message status
Webhook (push)API polling (pull)
How it worksThe 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.
FreshnessNear real time, as events are recorded.Only as fresh as your polling interval.
LoadOne request per event.Many requests, most returning “no change”.
You must buildA public HTTPS endpoint with verification, deduplication and monitoring.A scheduler, rate-limit handling and status reconciliation.
Best forDelivery 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.

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.

Illustrative example: delivery status event (JSON)
{
  "event_id": "evt_example_001",
  "event_type": "message.delivered",
  "message_id": "msg_example_123",
  "channel": "sms",
  "status": "DELIVERED",
  "timestamp": "2026-11-08T10:30:00Z"
}
Fields in the illustrative payload
FieldTypeWhat it is for
event_idStringIdentifies this notification. If the same event is delivered twice, the event ID is identical, so it is the key for deduplication.
event_typeStringNames what happened, for example a delivery, read, failure or reply. Route processing on this value.
message_idStringThe ID returned when the message was submitted. It links the event to the record in your system.
channelStringThe channel the event belongs to: sms, rcs, whatsapp or voice.
statusStringThe status the event reports, for example DELIVERED or FAILED.
timestampString (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.

  1. 01

    Create an HTTPS endpoint

    Build a route on your server that accepts POST requests with a JSON body over HTTPS.

  2. 02

    Share the callback URL

    Provide the endpoint URL to TXTPro for the channels and events you want to receive.

  3. 03

    Configuration and allowlisting

    TXTPro configures the callback, and any allowlisting, where applicable. The registration and allowlisting procedure is confirmed during onboarding.

  4. 04

    Receive events

    Your endpoint receives status and interaction events as they happen.

  5. 05

    Verify authenticity

    Check the signature or other authentication method confirmed for your account before trusting the payload.

  6. 06

    Validate the payload

    Check required fields, types and allowed values; reject anything that does not match.

  7. 07

    Store idempotently

    Record the event ID first so a retried or duplicated event is processed only once.

  8. 08

    Update message status

    Match the message ID to your record and update its status, respecting event order.

  9. 09

    Acknowledge quickly

    Return a 2xx response once the event is safely queued, and do slower work asynchronously.

  10. 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.

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

Request a demo

Tell us about your messaging requirements. Our team will walk you through the relevant channels, onboarding steps and integration options.