Webhooks
Our Email Webhooks API enables developers to configure and manage webhook endpoints for real-time email event notifications. The API provides comprehensive webhook management capabilities including webhook registration, retrieval, and deletion for various email event types.
Permissions Required
To access Email Webhooks API endpoints, the user must have valid permissions associated with their account:
EmailWebhook_Create
- Required for creating and updating webhook configurationsEmailWebhook_Read
- Required for reading webhook configurationsEmailWebhook_Delete
- Required for deleting webhook configurations
Fact Sheet
Feature | Support | Remark |
---|---|---|
Webhook Registration | Yes | Register webhook endpoints for real-time email event notifications |
Multiple Webhook Types | Yes | Support for 7 different webhook types (delivered, opened, click, etc.) |
Webhook Type Management | Yes | Retrieve and manage different webhook types per account |
Account-based Organization | Yes | Webhooks are organized by logical account IDs |
Webhook URL Validation | Yes | Validate webhook URLs during registration |
Webhook Deletion | Yes | Remove webhook configurations by type |
Managing Email Webhooks
The Email Webhooks API allows you to register webhook endpoints to receive real-time notifications for email events such as deliveries, bounces, clicks, and opens. Each webhook is associated with a logical account and webhook type.
Webhook Configuration
Create/Update Webhook Configuration
Register a new webhook or update an existing webhook configuration for email event notifications.
POST /v1/accounts/{logicalAccountId}/create
Content-Type: application/json
Path Parameters
Parameter | Type | Required | Description |
---|---|---|---|
logicalAccountId | UUID | Yes | The logical account identifier |
Request Headers
Header Name | Type | Required | Description |
---|---|---|---|
Content-Type | string | Yes | Must be "application/json" |
Authorization | string | Yes | Valid authorization token |
Request Body Example
{
"webhookType": "delivered",
"webhookUrl": "https://your-domain.com/webhook/email-events"
}
Successful Response (200)
{
"isSuccess": true,
"statusCode": "Ok",
"message": "Successfully created/updated webhook with id 123",
"data": 123
}
Error Responses
Invalid Request Body (400)
{
"isSuccess": false,
"statusCode": "InvalidRequest",
"message": "Request body is not valid",
"data": 0
}
Invalid Account ID (400)
{
"isSuccess": false,
"statusCode": "InvalidRequest",
"message": "Logical account id is not valid",
"data": 0
}
Invalid Webhook Type (400)
{
"isSuccess": false,
"statusCode": "InvalidRequest",
"message": "Webhook type is not valid",
"data": 0
}
Invalid Webhook URL (400)
{
"isSuccess": false,
"statusCode": "InvalidRequest",
"message": "Provide a valid url for webhook",
"data": 0
}
Get Webhook Configuration
Retrieve webhook configuration for a specific account and webhook type.
GET /v1/accounts/{logicalAccountId}/list?webhookType={webhookType}
Path Parameters
Parameter | Type | Required | Description |
---|---|---|---|
logicalAccountId | UUID | Yes | The logical account identifier |
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
webhookType | string | No | Specific webhook type to retrieve (e.g., "delivered", "bounces") |
Successful Response - Specific Webhook (200)
{
"isSuccess": true,
"statusCode": "Ok",
"message": "Successfully retrieved webhook for account 903e1cef-84b3-4500-a9a5-b2ca219f76f5 and type delivered",
"data": {
"webhookType": "delivered",
"url": "https://your-domain.com/webhook/email-events"
}
}
Successful Response - No Webhook Found (200)
{
"isSuccess": true,
"statusCode": "Ok",
"message": "No webhook found for account 903e1cef-84b3-4500-a9a5-b2ca219f76f5 and type delivered",
"data": null
}
Successful Response - Webhook Types (200)
When webhookType
is empty or "-1", returns available webhook types:
{
"isSuccess": true,
"statusCode": "Ok",
"message": "Successfully retrieved webhook type for account 903e1cef-84b3-4500-a9a5-b2ca219f76f5",
"data": "global"
}
Error Responses
Invalid Account ID (400)
{
"isSuccess": false,
"statusCode": "InvalidRequest",
"message": "Invalid account ID provided",
"data": null
}
Webhook Not Found (404)
{
"isSuccess": false,
"statusCode": "NotFound",
"message": "Webhook type not found",
"data": null
}
Delete Webhook Configuration
Remove a webhook configuration for a specific account and webhook type.
DELETE /v1/accounts/{logicalAccountId}/delete?webhookType={webhookType}
Path Parameters
Parameter | Type | Required | Description |
---|---|---|---|
logicalAccountId | UUID | Yes | The logical account identifier |
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
webhookType | string | Yes | Webhook type to delete (e.g., "delivered", "bounces", "click") |
Successful Response (200)
{
"statusCode": "Ok",
"statusMessage": "Successfully deleted 1 webhook(s)"
}
No Webhook Found Response (200)
{
"statusCode": "Ok",
"statusMessage": "No webhook found to delete"
}
Error Responses
Invalid Account ID (400)
{
"statusCode": "InvalidRequest",
"statusMessage": "Invalid account ID provided"
}
Invalid Webhook Type (400)
{
"statusCode": "InvalidRequest",
"statusMessage": "Webhook type is not valid"
}
Webhook Types
The system supports the following webhook types for different email events:
Webhook Type | Enum Value | Description | Events Included |
---|---|---|---|
global | 0 | All email events | All email events in single webhook |
delivered | 1 | Successful email deliveries | Email delivered to recipient's inbox |
opened | 2 | Email opens | Recipient opened the email |
click | 3 | Email link clicks | Recipient clicked on email links |
bounces | 4 | Email bounces (hard and soft) | Failed delivery attempts |
unsubscribes | 5 | Unsubscribe events | Recipient unsubscribed |
spamreports | 6 | Spam complaints | Email marked as spam |
Request Parameters
Webhook Configuration Request Body Fields
Field | Type | Required | Description |
---|---|---|---|
webhookType | string | Yes | Type of webhook: "global", "delivered", "opened", "click", "bounces", "unsubscribes", "spamreports" |
webhookUrl | string | Yes | HTTPS URL endpoint to receive webhook notifications |
Webhook Response Object
Field | Type | Description |
---|---|---|
webhookType | string | Type of webhook events |
url | string | Configured webhook endpoint URL |
Webhook URL Requirements
Requirement | Description |
---|---|
Protocol | Must use HTTPS for security |
Accessibility | Must be publicly accessible from CM servers |
Response | Should respond with 200 status for successful receipt |
Status Codes
Status Code | Description |
---|---|
200 | OK: Request processed successfully |
400 | Bad Request: Invalid request data or parameters |
404 | Not Found: Requested webhook not found |
500 | Internal Server Error: Server-side error |
Webhook Event Payload Structure
When events occur, webhooks will receive POST requests with payloads like:
{
"eventType": "delivered",
"messageId": "550e8400-e29b-41d4-a716-446655440000",
"recipient": "[email protected]",
"sender": "[email protected]",
"timestamp": "2024-03-15T10:30:00Z",
"accountId": "903e1cef-84b3-4500-a9a5-b2ca219f76f5",
"eventData": {
"subject": "Welcome to our service",
"status": "delivered",
"deliveryTime": "2024-03-15T10:30:00Z"
}
}
Best Practices
- HTTPS Only: Always use HTTPS URLs for webhook endpoints to ensure data security
- Idempotency: Design webhook handlers to be idempotent as events may be delivered multiple times
- Quick Response: Respond quickly (within 30 seconds) with HTTP 200 status to acknowledge receipt
- Error Handling: Implement proper error handling and logging in webhook endpoints
- Authentication: Consider implementing webhook signature validation for additional security
Example Use Cases
Email Delivery Tracking
Configure a webhook to track successful email deliveries:
{
"webhookType": "delivered",
"webhookUrl": "https://your-app.com/webhooks/email-delivery"
}
Bounce Management
Set up bounce handling for email list hygiene:
{
"webhookType": "bounces",
"webhookUrl": "https://your-app.com/webhooks/bounce-handler"
}
Engagement Tracking - Opens
Track email opens for analytics:
{
"webhookType": "opened",
"webhookUrl": "https://analytics.your-app.com/email-opens"
}
Engagement Tracking - Clicks
Track email clicks for analytics:
{
"webhookType": "click",
"webhookUrl": "https://analytics.your-app.com/email-clicks"
}
Unsubscribe Management
Handle unsubscribe events:
{
"webhookType": "unsubscribes",
"webhookUrl": "https://your-app.com/webhooks/unsubscribe-handler"
}
Spam Report Monitoring
Monitor spam complaints:
{
"webhookType": "spamreports",
"webhookUrl": "https://your-app.com/webhooks/spam-reports"
}
Global Event Handler
Receive all email events in a single webhook:
{
"webhookType": "global",
"webhookUrl": "https://your-app.com/webhooks/all-email-events"
}
Comprehensive Multi-Webhook Setup Example
Configure different webhooks for different event types:
# Delivery tracking
POST /v1/accounts/903e1cef-84b3-4500-a9a5-b2ca219f76f5/create
{
"webhookType": "delivered",
"webhookUrl": "https://your-app.com/webhooks/delivered"
}
# Bounce management
POST /v1/accounts/903e1cef-84b3-4500-a9a5-b2ca219f76f5/create
{
"webhookType": "bounces",
"webhookUrl": "https://your-app.com/webhooks/bounces"
}
# Open tracking
POST /v1/accounts/903e1cef-84b3-4500-a9a5-b2ca219f76f5/create
{
"webhookType": "opened",
"webhookUrl": "https://analytics.your-app.com/email-opens"
}
# Click tracking
POST /v1/accounts/903e1cef-84b3-4500-a9a5-b2ca219f76f5/create
{
"webhookType": "click",
"webhookUrl": "https://analytics.your-app.com/email-clicks"
}
# Unsubscribe handling
POST /v1/accounts/903e1cef-84b3-4500-a9a5-b2ca219f76f5/create
{
"webhookType": "unsubscribes",
"webhookUrl": "https://your-app.com/webhooks/unsubscribes"
}
# Spam report monitoring
POST /v1/accounts/903e1cef-84b3-4500-a9a5-b2ca219f76f5/create
{
"webhookType": "spamreports",
"webhookUrl": "https://your-app.com/webhooks/spam-reports"
}
Updated 1 day ago