Webhooks

Introduction

The Kero system can notify your system when the status of a message changes or when your customer sends you a reply.

The notification is done via a Webhook that you configure on the Kero App. When you configure the webhook you decide whether you are interested in sent messages or replies.

This page describes the information you need to implement the endpoint of such a webhook on your side.

Sent Message status updates

Your sent message webhook endpoint is invoked when the status of a message changes. For example: the status of a message changes when it is delivered to a mobile device and when the recipient reads the message.

While developing your webhook you can send test messages (see here for how to do that) and when configured correctly your endpoint will be invoked for those messages.

The different status values and the structure of the information posted to your endpoint is described in the next section. In the invoke parameters section there is some technical details about how your webhook is called. The final section describes the constraints that you must keep in mind when you implement your code.

The structure of the body that this webhook receives is an array of objects. Each object in the array has the following definition:

{
    eventId: string, 
    msgId: string, 
    oldStatus: Status,
    newStatus: Status,
    agentId: string,
    msisdn: string,
    userRef: string|null
}

The Status is one of the following:

• created: the message is new
• sent: a request to send was transferred to a downstream network provider
• delivered: the message was delivered to a mobile device
• read: the message was opened on the mobile device
• failed: the message failed to be relayed successfully
• fallback : the message was transferred to the downstream SMS provider
• test : a special status used for test messages only

Here is an example notification to get you started:

[
  {
    "agentId": "2c0YhEXCW5CKl6vY",
    "eventId": "9a606546b6fb18e35330fd5bb4ff1226",
    "msgId": "test-1733984754456956439-ed3fe72f-c3",
    "msisdn": "+000712321",
    "newStatus": "test",
    "oldStatus": "created",
    "userRef": "test-103"
  }
]

Reply notifications

Your reply message webhook endpoint is invoked whenever a customer replies to one of your brand agents.

The structure of the body that this webhook receives is an array of objects. Each object in the array has the following definition:

{
    eventId: string, 
    agentId: string,
    created: string,
    replyType: 'Text' | 'Suggestion',
    replyValue: string
}

The reply type is usually Text when the sender types in a response and Suggestion when the sender clicks on an action button.

Keep in mind that in high volume situations more than one reply can have the same eventId. The created timestamp would be a unique identified for a replay in the context of your account.

And here is an example:

  {
    "eventId": "581ca79f756390d2c56fb6710e6035a1",
    "agentId": "860979790425977",
    "created": "2025-12-02T13:43:09.692665Z",
    "msisdn": "+271231234",
    "replyType": "Text",
    "replyValue": "Thank you!"
  }

General guidelines

Your endpoint is invoked using the HTTP POST method. If your webhook is configured to include a custom header, those values will also be included in the POST request.

Security is important, and you should make use of this custom header for authentication or for header based access rules configured on your network.

In addition, the content-type: application/json is present; and the user agent is webhook-invoker for all requests.

In the case where your webhook misbehaves, an alert report is sent to the email address configured for your webhook. The idea is that these emails should be rare.

A failing webhook causes extra processing on our side, so we reserve the right do deactivate any webhook that consistently fails.

It is therefore important that you keep the few rules listed below in mind while you work on your solution:

1. Your webhook should return a success HTTP code (for example 200). If you return anything else the problem will be escalated.
2. Your webhook has at most 10 seconds to respond. If it takes longer, a timeout report will be escalated.
3. Your webhook may receive POST requests with a body that it has successfully processed before. You can use the eventId property if this is a particular issue for your use case.

In order to prevent flooding someone's mailbox the Kero system limits the number of emails. No more than one alert report is sent per day for every webhook that fails.

One final tip: Please use the Kero App to deactivate your test Webhook or delete it entirely when your development is done.