Webhooks

Message Events

Receive inbound messages and message status updates via webhook. See our guide for handling events with SDKs.

Headers

PINNACLE-SIGNING-SECRETstringRequired
Secret for verifying the authenticity of the request. Starts with `pss-` and is unique for each webhook. Find it at [webhooks](https://app.pinnacle.sh/dashboard/development/webhooks).

Payload

The payload of this webhook request is an object.
typeenumRequired
Type of webhook event. MESSAGE.STATUS for message status updates or MESSAGE.RECEIVED for inbound messages.
Allowed values:
conversationobjectRequired
Conversation metadata containing the conversation ID, sender, and recipient information.
statusenumRequired
Current status of the message.
directionenumRequired
Direction of the message flow.
Allowed values:
segmentsintegerRequired
Number of segments for this message.
sentAtstring or nullRequired
Timestamp when the message was sent in ISO 8601 format. Null if the message has not been sent yet.
messageobjectRequired

Content of an incoming or outgoing message. Discriminated by the type field.

deliveredAtstring or nullOptional
Timestamp when the message was delivered in ISO 8601 format. Null if not yet delivered or for inbound messages.
originalMessageIdstring or nullOptional

The unique identifier of the original RCS message that this fallback SMS/MMS was sent on behalf of. Always begins with the prefix msg_.

Only present on webhook events for fallback SMS/MMS messages. Use this to link the fallback back to the RCS message that could not be delivered. The message.id field on this event refers to the actual SMS/MMS that was sent — originalMessageId refers to the RCS message it replaced.

Null when the message is not a fallback.

fallbackMessageobject or nullOptional

Details of the fallback SMS/MMS message(s) that were actually sent to the recipient instead of the original RCS message.

Only present when the message status is FALLBACK_SENT. The message.id on this event refers to the original RCS message that could not be delivered. The fallbackMessage.ids contain the identifiers of the actual SMS/MMS messages that were sent.

Response

200
Return a 200 status to indicate that the data was received successfully