Webhooks are user-defined HTTP callbacks that are triggered by specific events. Whenever that trigger event occurs, the MIP API client sees the event, collects the data, and immediately sends a notification (HTTP request) to the Webhook URL specified in the application settings updating the status of sent messages or indicating when you receive a message.

It is important that your Webhook returns an HTTPS 2xx OK response to notifications. Otherwise the MIP API client considers that notification as failed and tries again after a delay.

Retrying failed webhooks

When the app to which we’re sending the webhook fails to send a response with a 2xx status code the package will consider the call as failed. The call will also be considered failed if the remote app doesn’t respond within 3 seconds. When a webhook call fails, we’ll retry the call two more times.

To not hammer the remote app we’ll wait some time between each attempt. By default, we wait 10 seconds between the first and second attempt, 100 seconds between the third and the fourth, 1000 between the fourth and the fifth and so on. The maximum amount of seconds that we’ll wait is 100 000, which is about 27 hours.


If you wish to have your callbacks signed and have made the proper configuration for this, the callbacks will have the following signature-related headers.

Name Description
Signature The signature generated by system with webhook id as secret


Message Status Notification

  "event": "mip:message:status",
  "payload": {
    "id": "a418d672-9781-4d97-b517-a56f7d95ad8a",
    "channel": "mip",
    "from": "919019120xxx",
    "to": "9190199xxxxx",
    "status": "sent|delivered|read|failed|deleted",
    "delivered_at": "2021-06-18T14:48:06.886358Z",
    "read_at": "2021-06-18T14:48:06.886358Z",
    "processed_at": "2021-06-18T14:48:06.886358Z",
    "timestamp": "2021-06-18T14:48:06.886358Z",
    "foreign_id": "your-business-identifier"