Webhooks

SMS Webhooks allow you to subscribe to real-time notifications about various SMS events that occur in MailerSend.

You can create a SMS webhook directly from your MailerSend account and listen for events so your integration can automatically trigger reactions.

SMS Webhooks overview

Setup

Currently, you can create a SMS webhook using the API endpoints listed below or directly from your account. Read more about webhooksopen in new window.

Available events

These are all the events you can listen to and send a notification for.

EventDescription
sms.sentFired when your SMS is sent from our sending servers. We are now waiting for a response from the receiving servers.
sms.deliveredFired when your SMS is successfully delivered with no errors.
sms.failedFired when your SMS failed to deliver.

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 sms.sent event:

{
  "type": "sms.sent",
  "sms_number_id": "7z3m5jgrogdpyo6n",
  "created_at": "2022-01-01T12:00:00.000000Z",
  "sms_webhook_id": "7z3m5jgrogdpyo6n",
  "url": "https://www.mailersend.com/webhook",
  "data": {
    "from": "+12345678901",
    "to": "+98765432109",
    "created_at": "2022-01-01T12:00:00.000000Z",
    "status": "sent",
    "sms_message_id": "6244233a7e194137e70e3bd2",
    "sms": {
      "id": "6244233a7e194137e70e3bd2",
      "from": "+12345678901",
      "to": "+98765432109",
      "text": "Lorem Ipsum is simply dummy text",
      "status": "sent",
      "segment_count": 1,
      "error_type": null,
      "error_description": null,
      "created_at": "2022-01-01T12:00:00.000000Z",
      "recipient": {
        "id": "6244233a7e194137e70e3bd2",
        "number": "+98765432109",
        "status": "active",
        "created_at": "2022-01-01T12:00:00.000000Z"
      }
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

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 create 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);
1
2
3
4
5
6
7

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.siteopen in new window or Pipedream.comopen in new window are useful tools for testing webhooks quickly, seeing how it works, and inspecting what's being sent—without any coding on your side.

Get a list of SMS webhooks

If you want to retrieve information about SMS webhooks, use this GET request:

GET https://api.mailersend.com/v1/sms-webhooks
1

Request parameters

ParameterTypeRequiredLimitationsDetails
sms_number_idstringyes

Get a single SMS webhook

To retrieve information about a single SMS webhook, use this GET request:

GET https://api.mailersend.com/v1/sms-webhooks/{sms_webhook_id}
1

Create an SMS webhook

Create a SMS webhook using this POST request:

POST https://api.mailersend.com/v1/sms-webhooks/
1

Request parameters

ParameterTypeRequiredLimitationsDetails
urlurlyesMax: 191
namestringyesMax: 191
eventsarrayyes
enabledbooleanoptional
sms_number_idstringyesExisting hashed SMS number ID.

Update a single SMS webhook

Update a SMS webhook using this PUT request:

PUT https://api.mailersend.com/v1/sms-webhooks/{sms_webhook_id}
1
ParameterTypeRequiredLimitationsDetails
urlurloptionalMax: 191
namestringoptionalMax: 191
eventsarrayoptional
enabledbooleanoptional

Delete an SMS webhook

Delete a SMS webhook using this DELETE request:

DELETE https://api.mailersend.com/v1/sms-webhooks/{sms_webhook_id}
1
Last Updated: