Webhooks
Receive real-time HTTP notifications about email delivery events. Configure webhook endpoints per message stream to track deliveries, bounces, opens, and more.
Event Types
When creating a webhook, specify which events you want to receive. Use * to subscribe to all events.
| Event | Description |
|---|---|
| sent | Amazon SES accepted the message for delivery |
| delivered | Recipient mail server accepted the message |
| bounced | Hard or soft bounce from recipient server |
| complained | Recipient marked the email as spam |
| rejected | Rejected by SES or suppressed before sending |
| failed | Send attempt failed after all retries exhausted |
| opened | Recipient opened the email |
| clicked | Recipient clicked a link in the email |
| * | Wildcard — receive all event types |
Create a Webhook
Register a webhook URL to receive events for a specific message stream. Requires JWT Bearer authentication.
Request Body
The HTTPS endpoint URL that will receive webhook payloads.
Array of event types to subscribe to. Use ["*"] for all events.
{
"url": "https://yourapp.com/webhooks/postject",
"events": ["delivered", "bounced", "complained"]
}Webhook Payload
When an event occurs, Postject sends a POST request to your webhook URL with the following JSON body:
{
"id": "msg_01hy4z9k2m...",
"type": "delivered",
"to": "user@example.com",
"subject": "Welcome aboard!",
"metadata": {},
"timestamp": "2024-01-15T10:30:00.000Z"
}Retry Policy
Failed webhook deliveries are retried automatically with exponential backoff:
- 3 attempts total per event
- 10 second timeout per request
- Exponential backoff between retries (5s, 10s, 20s)
Headers sent with each request: Content-Type: application/json and User-Agent: Postject-Webhook-Dispatcher/1.0
List Webhooks
Returns all registered webhooks for a given stream. Requires JWT Bearer authentication.
Delete a Webhook
Permanently removes a webhook. Events will no longer be sent to the registered URL. Requires JWT Bearer authentication.