MessageBird

The MessageBird webhook receives SMS delivery status updates from MessageBird. These events track whether messages were delivered, failed, or expired.

Endpoint

POST /api/rpc/webhooks/messagebird

Signature validation

MessageBird signs webhook requests using HMAC-SHA256.

Header	Description
MessageBird-Signature	HMAC-SHA256 signature (hex)
MessageBird-Request-Timestamp	Timestamp used in signature

The signature is computed over timestamp.payload. The timestamp must be within 5 minutes of the current time. Configure the signing key using the MESSAGEBIRD_SIGNING_KEY environment variable.

Supported statuses

MessageBird Status	Platform Event	Description
sent	sms_sent	Message sent to carrier
delivered	sms_delivered	Message delivered to recipient
delivery_failed	sms_failed	Delivery failed
expired	sms_undelivered	Message expired before delivery
scheduled	—	Skipped
buffered	—	Skipped

Payload fields

Field	Description
id	MessageBird’s unique message ID
recipient	Recipient phone number
statusDatetime	When the status changed (ISO 8601)
reference	Your custom reference
datacoding	Message encoding
mccmnc	Mobile country/network codes
statusErrorCode	Error code (if delivery failed)
statusReason	Error description (if delivery failed)

Response

{
  "success": true,
  "processed": 1
}

Setup

1. In your MessageBird dashboard, configure a webhook on your messaging channel.
2. Set the URL to your platform’s MessageBird webhook endpoint.
3. Set the MESSAGEBIRD_SIGNING_KEY environment variable to your MessageBird signing key.

Related pages

• Webhooks overview — how webhooks work
• Twilio SMS — alternative SMS provider integration