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 which can be retrieved through API or received through webhooks.

1. Anatomy of an event

The Event object has three key attributes:

A topic, which corresponds to the type of the related object
A type, which describes the action that happened
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

Topic	Lifecycle events
`payment_order`	Payment order lifecycle events
`incoming_payment`	Incoming payment lifecycle events
`return`	Return lifecycle events
`return_request`	Return request lifecycle events
`inquiry`	Inquiry lifecycle events
`balance`	Balance lifecycle events
`transaction`	Transaction lifecycle events
`counterparty`	Counterparty lifecycle events
`counterparty_account`	Counterparty account lifecycle events
`virtual_account`	Virtual account lifecycle events
`reconciliation`	Reconciliation lifecycle events
`expected_payment`	Expected payment lifecycle 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 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 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.