Events

Suggest Edits

An event is created when an object is created or updated, either by a user using the API or the dashboard or by 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.

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",
}

Existing events

The list of all events can be found in Event types.

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 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.

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 feature 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.

Updated 12 months ago