Webhooks

Numeral uses webhooks to notify your application when an event happens. Events include the creation of a new object or the update of an existing object. Webhooks are particularly helpful for asynchronous events, such as payment being executed by a bank or an account statement being received from a bank.

In order to use webhooks, you should create an endpoint on your server and register this endpoint with Numeral. To register an endpoint, email us.

For each event, Numeral will then send a POST API call to your endpoint in JSON format. This API call contains an event object. Learn more in the Events section.

To acknowledge receipt of an event, your endpoint must return a 2xx HTTP status code to Numeral within 5 seconds. If the endpoint takes longer to respond or returns an HTTP status code different from 2xx, the webhook will be re-sent at a later time with an exponential backoff.

To verify that events are sent by Numeral, a signature is included in each event's TX-Signature HTTP header. You should verify this signature using the RSASSA-PKCS1-v1_5 signature verification, with the public key provided by Numeral.

In order to guarantee that each event is unique, a unique ID is passed through as the HTTP header TX-Webhook-ID. An event that has been re-sent keeps the same ID.