Receiving a Webhook

On your end, you will be receiving HTTP POST requests on the endpoint you specified in the step above. They will contain a JSON body with the event payload and their content type will be set to application/json. Your endpoint should respond with HTTP status 200 or 201 in a timely manner (under 30 seconds), otherwise we will consider it not working and might not deliver the requests.

Verifying the Signature

Since the endpoint on which you will be receiving the requests must be publicly available, it is possible that someone will find it and try to send something that imitates Walnut webhook events to it. To make sure the events originated from Walnut, you may perform a verification procedure, for which you will need a shared key that was created for you when you set up the webhook.

The verification process goes as follows:

1. Take the raw body of the webhook request
2. Hash it with HMAC-SHA256, using the shared key from Walnut
3. Encode it using base16, make sure the results is lowercase
4. Compare the results with the contents of X-Walnut-Signature header from the request

The example code in Express.js might look similar to this:

app.post('/webhook', (req, res) => {
  let hmac = crypto.createHmac('sha256', process.env.WEBHOOK_KEY);
  hmac.update(req.rawBody);
  const calculatedSignature = hmac.digest('hex').toString('base16');
  const headerSignature = req.headers['x-walnut-signature']
  if (calculatedSignature == headerSignature) {
    console.log('Signature is valid');
    res.send({ok: true});
  } else {
    throw new Error('Signature invalid');
  }
})

Receiving an Error

When your endpoint returns a response other than 200 or 201, times out or fails for any other reason, we will retry sending the webhooks 20 times with an exponential backoff. The last attempt will be made between 40 and 48 hours after the first attempt was made.

Please note that this might result in webhook events arriving out of order, as each event has its own retrying strategy.

You can always test the connection to make sure the webhook was set up properly.