An event is created when an object is created or updated, either by a user using the API or the dashboard or by Mambu Payments (formerly Numeral). An update can be the update of any attribute, such as a status, a date, or any other data. An event takes the form of an Event object which can be retrieved through API or received through webhooks.

1. Anatomy of an event

The Event object has three key attributes:

1. A topic, which corresponds to the type of the related object
2. A type, which describes the action that happened
3. A data object, which contains the entire object created or updated

Below is an example of an event related to a payment order that has been created and is pending approval:

{
  "id": "ee04cd34-8474-48d4-b0fe-811c82fcafd1",
  "object": "event",
  "topic": "payment_order",
  "type": "pending_approval",
  "status": "delivered",
  "status_details": "",
  "related_object_id": "1391efba-40ff-4b16-a819-6c18a1490092",
  "related_object_type": "payment_order",
  "data": {
    "id": "1391efba-40ff-4b16-a819-6c18a1490092",
    "object": "payment_order",
    "amount": 314,
    "currency": "EUR",
    "type": "sepa_instant",
    "status": "pending_approval",
    […]
  },
  "created_at": "2022-06-24T10:23:57.450103Z",
}

2. Existing events

3. Using webhooks to automatically receive events

You can configure webhooks to automatically receive events in your application. With webhooks, you can fully automate internal processes based events that occur in Mambu Payments (formerly Numeral).

Examples of workflows that can be automated by leveraging events and webhooks include:

• When a payment order is created, inform operators that they need to approve it
• When a payment order fails, send a Slack notification to check its details
• When an expected payment is fully reconciled, book it in your accounting software
• When a new balance is created, send an email to the finance team

To learn more about webhooks, check our dedicated guide.

4. Manually retrieving events

We recommend to use webhooks to be automatically notified when new events are triggered. However, you can also manually retrieve events using the API. You can use the List all events API endpoint to retrieve events.

The topic, type, start_date, and end_date query parameters let you search for particular events that occurred within a specific time frame. Below is an example that uses the API to retrieve events related to payment orders executed between 2022-06-01 and 2022-06-30:

curl --request GET \
     --url 'https://sandbox.numeral.io/v1/events?topic=payment_order&type=executed&start_date=2022-06-01&end_date=2022-06-30' \
     --header 'Accept: application/json' \
     --header 'X-API-Key: YOUR_API_KEY'

Additionally, you can use the related_object_id filter to retrieve events related to a specific object, such as a payment order, a transaction, or a file:

curl --request GET \
     --url 'https://sandbox.numeral.io/v1/events?related_object_id=a3017f5e-8fbc-4747-8856-ce5d84669485' \
     --header 'Accept: application/json' \
     --header 'X-API-Key: YOUR_API_KEY'

To learn more about events, check the Events section in the API reference.

5. Retrying events in case of webhook failure

Whenever an event fails to be delivered, in other words we receive an HTTP status code other than 2xx on the webhook API call, it will be re-send again using the exponential back-off strategy up to 5 times.

If the event delivery mode is sequential or batched, the processing of the events stops in order to guarantee the order of receipt.

👍

Good practice

You should always first analyse and fix the webhook error and then, use the retry failed events API endpoint to re-send failed event and resume the events processing

❗️

Warning

You should not attempt to manually fix a payment status on your end if you have not received the corresponding event. There is a risk of debiting or crediting the end customer twice.

Illustration of bad practice:

• You receive an incoming instant payment but the incoming_payment:received event that triggers the actual funds credit on your end customer account could not be delivered due to the API call failure.
• You decide to manually credit your end customer without solving the webhook issue first and using the retry failed events API endpoint
• The webhook issue is solved later in the future, the event processing resumes and the incoming_payment:received event is finally delivered, triggering the funds credit on your end customer a second time.

6. Re-sending a delivered event

It is possible to re-send an already delivered event to the same or another webhook(s). This could serve different operational purposes such as data analysis or reporting. To achieve this, use the resend event endpoint.