Webhooks

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.