Message Hooks
Webhooks that push information about message delivery events to your configured target URL.
These webhooks are triggered for both email and SMS messages sent through Passcreator, including sendout campaigns and API-triggered messages.
Message webhooks are triggered at two points:
- On submission: When a message is submitted to the email/SMS provider
- On provider callback: When the email/SMS provider sends delivery status updates (delivered, bounced, etc.)
Message Sent
Pushes information when a message (email or SMS) has been successfully sent or delivered.
Event Type
message_sentTarget URL
Defined when subscribing.
When This Webhook Fires
The message_sent webhook fires when:
- A message is successfully submitted to the email/SMS provider (status: sent)
- The provider confirms successful delivery (status: delivered)
Submitted Values
JSON object containing the following information:
- Name
messageId- Type
- string
- (mandatory)
- Description
The UUID of the message.
- Name
channel- Type
- enum<'email', 'sms'>
- (mandatory)
- Description
The channel used to send the message.
- Name
recipient- Type
- string
- (mandatory)
- Description
The email address or phone number of the recipient.
- Name
status- Type
- enum<'sent', 'delivered'>
- (mandatory)
- Description
The current status of the message.
- Name
statusDetails- Type
- object
- (optional)
- Description
Additional details about the message status. Only present if additional information is available.
- Name
subject- Type
- string
- (mandatory)
- Description
The subject line (for email) or a preview of the message content (for SMS).
- Name
passInstanceId- Type
- string | null
- (mandatory)
- Description
The UUID of the associated pass instance, if the message was sent for a specific pass. Null if not associated with a pass.
- Name
templateId- Type
- string | null
- (mandatory)
- Description
The UUID of the pass template associated with the message, if applicable. Null if not associated with a template.
- Name
createdOn- Type
- string
- (mandatory)
- Description
ISO 8601 formatted date when the message was created.
- Name
submittedOn- Type
- string | null
- (mandatory)
- Description
ISO 8601 formatted date when the message was submitted to the provider. Null if not yet submitted.
- Name
signature- Type
- string
- (mandatory)
- Description
Hexadecimal signature for verifying the webhook payload authenticity.
- Name
signedData- Type
- string
- (mandatory)
- Description
JSON string of the original payload used to generate the signature.
Example Payload (Email)
Webhook POST request body - Email
{
"messageId": "12fd53c5-863e-4056-9dbf-2525fa175523",
"channel": "email",
"recipient": "customer@example.com",
"status": "sent",
"subject": "Your pass is ready!",
"passInstanceId": "abc12345-863e-4056-9dbf-2525fa175523",
"templateId": "def67890-863e-4056-9dbf-2525fa175523",
"createdOn": "2024-01-15T10:30:00+00:00",
"submittedOn": "2024-01-15T10:30:05+00:00",
"signature": "a1b2c3d4...",
"signedData": "{\"messageId\":\"12fd53c5...\"}"
}
Example Payload (SMS)
Webhook POST request body - SMS
{
"messageId": "22fd53c5-863e-4056-9dbf-2525fa175524",
"channel": "sms",
"recipient": "+1234567890",
"status": "delivered",
"subject": "Your verification code is 123456...",
"passInstanceId": "abc12345-863e-4056-9dbf-2525fa175523",
"templateId": "def67890-863e-4056-9dbf-2525fa175523",
"createdOn": "2024-01-15T10:30:00+00:00",
"submittedOn": "2024-01-15T10:30:02+00:00",
"signature": "e5f6g7h8...",
"signedData": "{\"messageId\":\"22fd53c5...\"}"
}
Message Failed
Pushes information when a message (email or SMS) has failed to send or was rejected.
Event Type
message_failedTarget URL
Defined when subscribing.
When This Webhook Fires
The message_failed webhook fires when:
- A message is skipped (invalid recipient, unsubscribed, rate limit exceeded) (status: skipped)
- The email bounces (status: bounced)
- The message is marked as spam (status: spam)
- The recipient unsubscribes (status: unsubscribed)
Submitted Values
JSON object containing the following information:
- Name
messageId- Type
- string
- (mandatory)
- Description
The UUID of the message.
- Name
channel- Type
- enum<'email', 'sms'>
- (mandatory)
- Description
The channel used to send the message.
- Name
recipient- Type
- string
- (mandatory)
- Description
The email address or phone number of the recipient.
- Name
status- Type
- enum<'skipped', 'bounced', 'spam', 'unsubscribed'>
- (mandatory)
- Description
The status indicating why the message failed.
- Name
statusDetails- Type
- object
- (optional)
- Description
Details about why the message failed.
- Name
statusDetails.reason- Type
- string
- (optional)
- Description
Human-readable reason for the failure.
- Name
statusDetails.error- Type
- string
- (optional)
- Description
Error message from the email/SMS provider.
- Name
statusDetails.error_related_to- Type
- string
- (optional)
- Description
Classification of the error type.
- Name
subject- Type
- string
- (mandatory)
- Description
The subject line (for email) or a preview of the message content (for SMS).
- Name
passInstanceId- Type
- string | null
- (mandatory)
- Description
The UUID of the associated pass instance, if the message was sent for a specific pass. Null if not associated with a pass.
- Name
templateId- Type
- string | null
- (mandatory)
- Description
The UUID of the pass template associated with the message, if applicable. Null if not associated with a template.
- Name
createdOn- Type
- string
- (mandatory)
- Description
ISO 8601 formatted date when the message was created.
- Name
submittedOn- Type
- string | null
- (mandatory)
- Description
ISO 8601 formatted date when the message was submitted to the provider. Null if the message was skipped before submission.
- Name
signature- Type
- string
- (mandatory)
- Description
Hexadecimal signature for verifying the webhook payload authenticity.
- Name
signedData- Type
- string
- (mandatory)
- Description
JSON string of the original payload used to generate the signature.
Example Payload (Skipped - Invalid Email)
Webhook POST request body - Skipped
{
"messageId": "32fd53c5-863e-4056-9dbf-2525fa175525",
"channel": "email",
"recipient": "invalid-email",
"status": "skipped",
"statusDetails": {
"reason": "The given email address invalid-email is not valid."
},
"subject": "Your pass is ready!",
"passInstanceId": "abc12345-863e-4056-9dbf-2525fa175523",
"templateId": "def67890-863e-4056-9dbf-2525fa175523",
"createdOn": "2024-01-15T10:30:00+00:00",
"submittedOn": null,
"signature": "i9j0k1l2...",
"signedData": "{\"messageId\":\"32fd53c5...\"}"
}
Example Payload (Bounced)
Webhook POST request body - Bounced
{
"messageId": "42fd53c5-863e-4056-9dbf-2525fa175526",
"channel": "email",
"recipient": "nonexistent@example.com",
"status": "bounced",
"statusDetails": {
"error": "User unknown",
"error_related_to": "recipient"
},
"subject": "Your pass is ready!",
"passInstanceId": "abc12345-863e-4056-9dbf-2525fa175523",
"templateId": "def67890-863e-4056-9dbf-2525fa175523",
"createdOn": "2024-01-15T10:30:00+00:00",
"submittedOn": "2024-01-15T10:30:05+00:00",
"signature": "m3n4o5p6...",
"signedData": "{\"messageId\":\"42fd53c5...\"}"
}
Example Payload (Unsubscribed)
Webhook POST request body - Unsubscribed
{
"messageId": "52fd53c5-863e-4056-9dbf-2525fa175527",
"channel": "email",
"recipient": "unsubscribed@example.com",
"status": "skipped",
"statusDetails": {
"reason": "Email address unsubscribed@example.com is unsubscribed."
},
"subject": "Your pass is ready!",
"passInstanceId": null,
"templateId": null,
"createdOn": "2024-01-15T10:30:00+00:00",
"submittedOn": null,
"signature": "q7r8s9t0...",
"signedData": "{\"messageId\":\"52fd53c5...\"}"
}
Status Reference
The following table shows all possible status values and which webhook they trigger:
| Status | Webhook | Description |
|---|---|---|
| sent | message_sent | Message successfully submitted to provider |
| delivered | message_sent | Provider confirmed delivery |
| skipped | message_failed | Message skipped (invalid recipient, unsubscribed, rate limited) |
| bounced | message_failed | Email bounced or was blocked |
| spam | message_failed | Message marked as spam |
| unsubscribed | message_failed | Recipient unsubscribed via email link |
| opened | - | Email opened (no webhook triggered) |
| queued | - | Message queued for sending (no webhook triggered) |
| pending | - | Message pending processing (no webhook triggered) |
Message webhooks support optional template binding, similar to other webhook types. When bound to a specific template, the webhook will only fire for messages associated with passes from that template.