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.

TopicDescriptionLifecycle events
payment_orderPayment order lifecycle event.Payment order lifecycle events
incoming_paymentIncoming payment lifecycleIncoming payment lifecycle events
returnReturn lifecycle event.Return lifecycle events
return_requestReturn request lifecycle event.Return request lifecycle events
inquiryInquiry lifecycle event.Inquiry lifecycle events
balanceBalance lifecycle event.Balance lifecycle events
transactionTransaction lifecycle event.Transaction lifecycle events
counterpartyCounterparty lifecycle event.Counterparty lifecycle events
counterparty_accountCounterparty lifecycle event.Counterparty account lifecycle events
virtual_accountVirtual account lifecycle event.Virtual account lifecycle events
reconciliationReconciliation lifecycle event.Reconciliation lifecycle events
expected_paymentExpected payment lifecycle event.Expected payment lifecycle events
fileFile lifecycle event.File lifecycle events
eventEvent 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.