# Webhooks
Webhooks allow you to subscribe to real-time notifications about various events that occur in MailerSend.
Listen for events on your MailerSend account so your integration can automatically trigger reactions. You can create a webhook directly from your account.
# Webhooks overview
# Setup
Currently, you can create a webhook using API endpoints listed below or directly from your account. Read more
# Available events
These are all the events you can listen to and send a notification for.
Event | Description |
---|---|
activity.sent | Fired when your email was sent from our sending servers. We are now waiting for a response from the receiving servers. |
activity.delivered | Fired when your email was successfully delivered with no errors. |
activity.soft_bounced | Fired when your email was not delivered because it soft bounced. |
activity.hard_bounced | Fired when your email was not delivered. |
activity.opened | Fired when the recipient received your email and opened it. |
activity.clicked | Fired when the recipient clicked a link in your email. |
activity.unsubscribed | Fired when the recipient unsubscribes from your emails. |
activity.spam_complaint | Fired when the recipient marks your emails as spam or junk. |
# Payload example
Our responses contain fat payloads including the information about the event-related object so there is no need to make an additional API request.
An example of activity.sent
event:
{
"type": "activity.sent",
"domain_id": "yv69oxl5kl785kw2",
"created_at": "2020-11-27T10:08:08.298647Z",
"webhook_id": "2351ndgwr4zqx8ko",
"url": "https://your-domain.com/webhook",
"data": {
"object": "activity",
"id": "5fc0d006b42c3e16e1774882",
"type": "sent",
"created_at": "2020-11-27T10:08:06.258000Z",
"email": {
"object": "email",
"id": "5fc0d003e7a5e7035446aa32",
"created_at": "2020-11-27T10:08:03.923000Z",
"from": "test@mailersend.com",
"subject": "Test email",
"status": "sent",
"tags": null,
"message": {
"object": "message",
"id": "5fc0d003f718c90162341852",
"created_at": "2020-11-27T10:08:03.017000Z"
},
"recipient": {
"object": "recipient",
"id": "5f6887d6fd913a6523283fd2",
"email": "test@mailersend.com",
"created_at": "2020-09-21T11:00:38.184000Z"
}
},
"morph": null
}
}
# Security
Webhook requests made by MailerSend include a Signature
header. It contains a string generated by hashing the data sent to your webhook endpoint with an individual Signing Secret. A signing secret is a random string that is generated when you are creating a webhook.
Verifying a signature:
// $signature - a header sent by MailerSend, please refer to your framework or PHP manual on how to read the Signature header
// $requestContent - please refer to your framework or PHP manual on how to read the request content
$computedSignature = hash_hmac('sha256', $requestContent, $signingSecret);
return hash_equals($signature, $computedSignature);
# Retrying failed webhooks
When your webhook receives a response other than a 2xx
code from your endpoint URL or if the endpoint doesn’t respond within 3 seconds, it will show up as a failed attempt in the log section of your webhook. If it receives a 2xx
, then it will show as a success.
If a webhook call fails, MailerSend will retry the call a couple of times, waiting 10 seconds between the first and second attempt, and 100 seconds between the second and the third attempt. This is to avoid hammering the application you want to send the information to.
# Useful tools
Webhook.site or Pipedream.com are useful tools for testing webhooks quickly, seeing how it works, and inspecting what's being sent—without any coding on your side.
# List webhooks
If you want to have information about webhooks, use this GET
request:
GET https://api.mailersend.com/v1/webhooks
# Request parameters
Parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | string | yes |
# Get a webhook
Get a single webhook, use this GET
request:
GET https://api.mailersend.com/v1/webhooks/{webhook_id}
# Create a webhook
Create a webhook using this POST
request:
POST https://api.mailersend.com/v1/webhooks/
# Request parameters
Parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
url | url | yes | ||
name | string | yes | Max: 191 | |
events | array | yes | ||
enabled | boolean | optional | ||
domain_id | string | yes | Existing hashed domain ID |
# Update a webhook
Update a webhook using this PUT
request:
PUT https://api.mailersend.com/v1/webhooks/{webhook_id}
Parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
url | url | optional | ||
name | string | optional | Max: 191 | |
events | array | optional | ||
enabled | boolean | optional |
# Delete a webhook
Delete a webhook using this DELETE
request:
DELETE https://api.mailersend.com/v1/webhooks/{webhook_id}