Why use the webhook?

When integrating Ding, you might want your system to receive events as they occur in your Ding apps, so that your backend systems can execute actions accordingly.

To register a webhook, you need to provide a callback_url along with your Authentication request. After registration, Ding can push real-time event data to your webhook endpoint when events happen in your app.

The event object

There are two types of events that can be sent to your webhook endpoint:

  • Authentication events: sent when an Authentication is created.
  • Attempt events: sent when a message is sent to the user.
{
  "id": "90c7e8b2-203a-4984-ba25-6cf93d8fdbac",
  "auth_uuid": "f54b6bcc-3638-4437-83c8-1f76631c9403",
  "type": "authentication",
  "recipient_phone_number": "+33xxxxxxxx",
  "price": {
    "amount": 0.009,
    "currency": "EUR"
  },
  "time": "2023-05-09T12:09:31+0000"
}

How to set up your Webhook

To start receiving webhook events in your app, create and register a webhook endpoint by following the steps below. You can register and create one endpoint to handle several different event types at once, or set up individual endpoints for specific events.

1

Implement the handler

Develop a webhook endpoint function to receive event data POST requests.

2

Pass the URL

Add your webhook endpoint URL to your Authentication requests to start receiving events.

3

Return OK

Return a 200 OK HTTP response to the POST request to acknowledge receipt of the event. If you don’t, Ding will retry sending the event for 2 weeks.

To avoid replaying events, we recommend that you use the *_uuid field to identify and deduplicate individual events.


Next steps

Follow the API reference to get detailed information about the Ding API.

API Reference

Learn more about Ding’s API endpoints.