Webhooks

Niva uses webhooks to send updates about various events. Webhooks provide a way for your application to receive real-time notifications when certain events occur.

Overview

Webhooks are HTTP callbacks that are triggered by specific events. When such an event occurs, Niva makes an HTTP POST request to the URL you specified in your API configuration.

Webhook schema

The payload sent by Niva to your webhook endpoint follows this schema:

Webhook Event

Webhook events

event	description	Payload Object
submission.processed	Submission has finished processing and data is ready.	Submission
document.validated	Document validation has been completed. Document can be valid or invalid, information is in the event payload.	Document

Retry and Failure

Successful Processing: If you've successfully processed the webhook, respond with an HTTP status code in the 2XX range within 15 seconds.

Retry Mechanism: If your endpoint does not respond with a 2XX status code, Niva will retry the webhook once before marking it as failed.

Failure Handling: You can replay any failed webhooks through your API config panel.

Verifying webhooks

To ensure the authenticity of the webhook requests, each request includes three headers that can be used to verify the authenticity of the message:

webhook-id: the unique message identifier for the webhook message.

webhook-timestamp: timestamp in seconds since epoch.

webhook-signature: the Base64 encoded list of signatures (space delimited).

Constructing the signed content

The content to sign is composed by concatenating the id, timestamp and payload, separated by the full-stop character (.). In code, it will look something like:

signedContent = "${webhook_id}.${webhook_timestamp}.${body}"

Where body is the raw body of the request. The signature is sensitive to any changes, so even a small change in the body will cause the signature to be completely different. This means that you should not change the body in any way before verifying.

Determining the expected signature

HMAC with SHA-256 is used to sign our webhooks requests.

So to calculate the expected signature, you should HMAC the signed_content from above using the base64 portion of your signing secret (this is the part after the whsec_ prefix) as the key. For example, given the secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw you will want to use MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw. The signing secret is unique to each endpoint you configure and is available in the API config panel.

For example, this is how you can calculate the signature in Node.js:

Verifying the Signature

This generated signature should match one of the ones sent in the webhook-signature header.

The webhook-signature header is composed of a list of space delimited signatures and their corresponding version identifiers. The signature list is most commonly of length one. Though there could be any number of signatures. For example:

v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo= v2,MzJsNDk4MzI0K2VvdSMjMTEjQEBAQDEyMzMzMzEyMwo=

Make sure to remove the version prefix and delimiter (e.g. v1,) before verifying the signature.

Static Source IP Addresses

In case your webhook receiving endpoint is behind a firewall or NAT, you may need to allow traffic from the webhook source static IP addresses.

This is the full list of IP addresses that webhooks may originate from.

44.228.126.217
50.112.21.217
52.24.126.164
54.148.139.208
2600:1f24:64:8000::/56

Webhooks

Overview#

Webhook schema#

Webhook events#

Retry and Failure#

Verifying webhooks#

Constructing the signed content#

Determining the expected signature#

Verifying the Signature#

Static Source IP Addresses#