Webhook Requests

Webhook requests are the way of being notified about the entities that are updated on Javelin. You need to implement an endpoint to accept webhook requests from Javelin. Here is the step by step guide how to implement webhook request clients for Javelin.

Validate webhook request signature

Javelin will provide you a secret once you subscribe to the webhooks. Javelin attaches a signature which is created using the secret provided to you. Once you receive a webhook request, you first need to check if the signature is valid using the secret and the algorithm as described below.

The signature is in the Signature header in webhook request. You need to be sure that the value in the Signature header is identical with the one you generate, so you can be sure that the webhook requests are coming from Javelin rather than an unexpected source.

Generating Signature

Javelin uses Hash-based Message Authentication Code (HMAC) with SHA256 hash function to sign the request. You will use the secret as key and request body as the data.

The authentication code made using secret and request body should be identical with the one in Signature header.

Here are some example implementations on various languages.

// PHP
hash_hmac('sha256', <Request body as JSON String>, <Secret>);

// Python
hmac.new(str(<Secret>), msg=<Request Body as JSON String>, digestmod=hashlib.sha256).hexdigest().lower()

Accepting webhook requests

Javelin makes POST requests to your endpoints. To acknowledge receipt of a request, your endpoint must return a 2xx HTTP status code to Javelin. All response codes outside this range, including 3xx codes, indicate to Javelin that you did not receive the request.

If Javelin does not receive a 2xx HTTP status code, the notification attempt is repeated. After multiple failures to send the request over multiple days, Javelin marks the request as failed and stops trying to send it to your endpoint.

Because properly acknowledging receipt of the webhook request is so important, your endpoint should return a 2xx HTTP status code prior to any complex logic that could cause a timeout.