Messaging Webhooks

Messaging webhooks notify your application when a message arrives or an outgoing message’s delivery status changes.

Configure publicly accessible HTTPS endpoints to receive these notifications. Webhook requests use form fields for POST or query parameters for GET, rather than a JSON request body.

Receive incoming messages

Configure the receiving TextGrid phone number’s SMS URL and SMS Method.

The method defaults to POST. When using POST, TextGrid sends:

Content-Type: application/x-www-form-urlencoded

Incoming message fields

Field	Description
`MessageSid`	Unique identifier for the incoming message.
`SmsSid`	The same incoming message identifier.
`SmsMessageSid`	The same incoming message identifier.
`AccountSid`	Identifier of the receiving TextGrid account.
`From`	Sender’s phone number.
`To`	Receiving TextGrid phone number.
`Body`	Message text. A null value may be omitted.
`SmsStatus`	`received` for an incoming message.
`NumMedia`	Number of media attachments.
`NumSegments`	Number of message segments.
`ApiVersion`	`2010-04-01`.

Counts are transmitted as text in form fields or query parameters. Convert them to integers if your application needs numeric values.

MMS attachments

Incoming MMS notifications include indexed fields for each attachment:

Field	Description
`MediaUrl0`	URL for the first attachment.
`MediaContentType0`	MIME type of the first attachment.
`MediaUrl1`	URL for the second attachment, when present.
`MediaContentType1`	MIME type of the second attachment, when present.

Indexes begin at 0. Use NumMedia to determine how many attachments to process.

Acknowledge an incoming message

TextGrid recognizes these response codes as successful acknowledgments:

200 OK
201 Created
202 Accepted
204 No Content

If your application does not need to reply automatically, return an accepted status with an empty body.

Send an automatic reply

Your endpoint can return messaging TwiML to request a reply:

<Response>
  <Message>
    <Body>Thanks for your message. Our team will respond shortly.</Body>
  </Message>
</Response>

Return XML with an appropriate content type, such as application/xml.

Automatic response processing applies when TextGrid has not already sent an automatic reply for the incoming message.

Track outgoing delivery status

When sending a message, supply a statusCallback URL to receive delivery notifications.

A per-message statusCallback takes precedence over the phone number’s configured Status Callback URL and uses POST.

When no per-message URL is supplied, TextGrid uses the phone number’s configured status callback URL and method. The method defaults to POST and can be configured as GET.

Delivery status fields

Field	Description
`MessageSid`	Identifier of the outgoing message.
`SmsSid`	The same outgoing message identifier.
`AccountSid`	Identifier of the sending TextGrid account.
`From`	Sending TextGrid phone number.
`To`	Destination phone number.
`MessageStatus`	Current delivery status.
`SmsStatus`	The same value as `MessageStatus`.
`Segments`	Number of message segments, transmitted as text.
`ApiVersion`	`2010-04-01`.
`SmsStatusDetail`	Additional mapped error information, included when available.

Status values can include sent, delivered, failed, and undelivered. Treat them as strings; the available values and transitions can depend on the messaging provider.

Acknowledge delivery notifications with 200, 201, 202, or 204. Delivery status callbacks do not request an automatic message reply.

Verify the webhook signature

TextGrid signs webhook requests using your account’s Webhook Secret and sends the result in:

X-TextGrid-Signature: SIGNATURE_VALUE

The signing input depends on the request method:

Method	Signing input
`GET`	The full requested public URL, including its encoded query string.
`POST`	The original callback URL, including any existing query string, concatenated directly with the request body.

Before calculating the signature, replace each non-ASCII UTF-16 character in the signing text with a literal \uXXXX escape using lowercase hexadecimal—for example, é becomes \u00e9.

Convert the resulting signing text and your Webhook Secret into UTF-8 byte arrays. Compute HMAC-SHA1 using the secret’s bytes as the key and the signing text’s bytes as the message, then Base64-encode the resulting hash.

Preserve the original encoding and parameter order when verifying a request. Parsing and rebuilding a form body can change the signature.

If your application is behind a reverse proxy, use the public URL that TextGrid called rather than an internal hostname.

Retries and fallback behavior

Incoming messages

TextGrid attempts the primary incoming-message request at most twice. The second attempt occurs after a one-second delay when the first attempt ends with a transport result of status code 0.

An actual HTTP response, including an error response, stops that retry loop.

If an automatic reply has not already been sent and the primary request is unsuccessful, TextGrid can call the phone number’s configured SMS Fallback URL once, using its configured fallback method.

The endpoint timeout defaults to 15 seconds and can be configured.

Delivery status notifications

The delivery status sender makes one request. It does not implement the incoming-message retry loop or fallback behavior.

Handle repeated notifications

Webhook delivery is not guaranteed to occur exactly once. Your endpoint should tolerate repeated notifications.

For incoming messages, use MessageSid to prevent duplicate processing or replies. For delivery updates, use the message identifier together with the status so that a later status change can still be processed.