Introduction to webhooks
Numeral uses webhooks to notify your application when an event is created. Webhooks are particularly helpful for asynchronous events, such as a payment being executed by the bank or an account statement being received from a bank.
Events are 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.
For each event, Numeral will send a POST
request to your API endpoint in JSON format. This API request contains an event
object.
Event structure
{
"id": "35bb6411-290d-478e-a478-2f84146c2ddf",
"object": "event",
"topic": "payment_order",
"type": "executed",
"related_object_id": "25102c0f-fc25-44e7-9402-cae6d61ad47f",
"related_object_type": "payment_order",
"status": "delivered",
"status_details": "",
"created_at": "2023-02-01T17:13:15.087995Z",
"data": {
"id": "25102c0f-fc25-44e7-9402-cae6d61ad47f",
"idempotency_key": "",
"object": "payment_order",
"connected_account_id": "a0d22970-3b30-44c9-a5ea-fac6707f6b80",
"connected_account": "a0d22970-3b30-44c9-a5ea-fac6707f6b80",
"type": "sepa",
"direction": "credit",
"amount": 75000,
"currency": "EUR",
"reference": "Invoice ID 89230927",
"value_date": "2023-02-01",
"originating_account": {
"bank_code": "SOGEFRPP",
"holder_name": "SoftwareCo",
"account_number": "FR7601234567890627967100010",
"holder_address": {
"line_1": "1, rue de l'Abondance",
"line_2": "",
"postal_code": "69003",
"city": "Lyon",
"region_state": "",
"country": "FR"
}
},
"receiving_account_id": "",
"receiving_account": {
"bank_code": "BNPAFRPPXXX",
"holder_name": "PartnerCo",
"account_number": "FR7601234567891127967100082",
"holder_address": {
"line_1": "1, rue de la Bourse",
"line_2": "",
"postal_code": "59000",
"city": "Lille",
"region_state": "",
"country": "FR"
}
},
"direct_debit_mandate": null,
"status": "executed",
"status_details": "",
"auto_approval": false,
"reconciliation_status": "unreconciled"
"reconciled_amount": 0,
"metadata": {},
"bank_data": {
"file_id": "b251f19a-55a4-459a-8fb0-8dc2b72443d4",
"message_id": "230201030031Fzmc",
"end_to_end_id": "25102c0ffc2544e79402cae6d61ad47f",
"transaction_id": "25102c0ffc2544e79402cae6d61ad47f",
"original_instruction_id": "25102c0ffc2544e79402cae6d61ad47f"
},
"created_at": "2023-02-01T17:10:00.248706Z",
},
}
Event topics and types
Events have a topic
and a type
. The topic
corresponds to the type of the object that has been created or updated. The type
corresponds to the exact update on the object.
Topic | Description | Lifecycle events |
---|---|---|
payment_order | Payment order lifecycle event. | Payment order lifecycle events |
incoming_payment | Incoming payment lifecycle | Incoming payment lifecycle events |
return | Return lifecycle event. | Return lifecycle events |
return_request | Return request lifecycle event. | Return request lifecycle events |
inquiry | Inquiry lifecycle event. | Inquiry lifecycle events |
balance | Balance lifecycle event. | Balance lifecycle events |
transaction | Transaction lifecycle event. | Transaction lifecycle events |
counterparty | Counterparty lifecycle event. | Counterparty lifecycle events |
counterparty_account | Counterparty lifecycle event. | Counterparty account lifecycle events |
virtual_account | Virtual account lifecycle event. | Virtual account lifecycle events |
reconciliation | Reconciliation lifecycle event. | Reconciliation lifecycle events |
expected_payment | Expected payment lifecycle event. | Expected payment lifecycle events |
file | File lifecycle event. | File lifecycle events |
event | Event lifecycle event. | Event lifecycle events |
Registering an API endpoint
In order to use webhooks, you should create an API endpoint on your server and register it using the Numeral's dashboard. To register an API endpoint, go to Developers > Webhooks > Add webhook.
By default, all event topics and types will be sent to your API endpoint. If you would like to only receive specific event topics or types, please get in touch at [email protected].
Acknowledgment of receipt
To acknowledge the receipt of an event, your API endpoint must respond with a 2xx
HTTP status code to Numeral within 5 seconds.
To guarantee that your API endpoint receives the events in the correct order:
- The next event is sent once the previous event has been received
- Events are delivered steadily over time one by one
- The processing of events stops at the first failed event
The Resend failed events feature should be used to resend failed events and resume the sending and delivery of events.
Exponential back-off strategy
If your API endpoint takes longer to respond or returns an HTTP status code different from 2xx
, the event will be set to pending_retry
status and re-sent up to 5 times during a ~2.8-hour period using an exponential back-off strategy. The event is set to failed
status after 6 unsuccessful deliveries.
Webhook event idempotency
In order to guarantee that each event is unique, a unique ID is passed through the TX-Webhook-ID
HTTP header. An event that has been sent twice will be sent with the same header value.
Event signature
All webhooks sent by Numeral are signed so that you can verify their authenticity and check that they haven't been modified in transit. Check our dedicated guide to learn how to verify the signature.