Webhooks

Herald uses webhooks to send an automatic update when a quote has finished processing and is no longer [.h-code]pending[.h-code].

To use webhooks, a platform must provide a webhook URL in the standard format exemplified in the URL Format section. Then, when a valid submission is completed, Herald will send a [.h-code]POST[.h-code] request containing the quote data to the provided webhook URL. You can view the [.h-code]POST[.h-code] request format in the Request Format section.

Please note: the time it takes to generate a quote varies based on carrier, so don't worry if quotes aren't sent to the webhook URL instantly. To give an idea, some carriers can take up to 45 seconds to process a quote.

Set Up

Reach out to a member of the Herald team to set up a webhook URL.

URL Format‍

[.h-code]http(s)://(www.)domain.com/resource[.h-code]

Request Format

The webhook URL provided to Herald will receive requests in the following format:

Security

In order to ensure that the request coming in to the webhook URL is from Herald, we have included [.h-code]x-herald-signature[.h-code] as a header in the [.h-code]POST[.h-code] request. The value of this header is a SHA-256 hash of the secret key provided to the platform concatenated with the stringified version of the request body. This ensures that the secret key is correct as well as ensure the content of the request has not been modified.

To verify this signature, the server consuming the webhook will need to concatenate the secret key with the stringified version of the request body and generate the SHA-256 hash. An authenticated request will meet the requirement that the [.h-code]x-herald-signature[.h-code] and the generated SHA-256 hash are equal.

Below is an example implementation of a simple Express server with a [.h-code]POST[.h-code] endpoint that authenticates the Herald signature header and request:

Copied

const express = require('express');
const bodyParser = require('body-parser');
const sha256 = require('crypto-js/sha256');
const Base64 = require('crypto-js/enc-base64');

const router = express.Router();
const app = express();

// Here we are configuring express to use body-parser as middle-ware
app.use(bodyParser.urlencoded({ extended: false }));
app.use(bodyParser.json());

// Webhook POST endpoint
router.post('/webhook', (request, response) => {
  // Access Herald signature header
  const signature = request.headers['x-herald-signature'];
  // Secret key that is unique to the platform
  const secretKey = 'abc-123';
  // String value of secret key concatenated with string version of the request body
  const concatenatedValue = secretKey + JSON.stringify(request.body);
  const hashedValue = Base64.stringify(sha256(concatenatedValue, secretKey));
  if (signature === hashedValue) {
    console.log('Request body is valid');
  } else {
    console.log('Request body is NOT valid');
  }
  // Return a 200 status code to communicate request has been processed
  response.status(200).end();
});

// Add router in the Express app
app.use('/', router);
app.listen(5000);
 

Retries

Herald will send the webhook event when the quote finishes processing. This initial time will vary based on carrier response times. If there is a non-200 response from the configured webhook endpoint, Herald will retry sending the webhook up to two additional times at intervals spaced a few minutes apart.

[.icon-circle-blue][.icon-circle-blue]Note: The Herald signature and payload for each retry attempt will be the same as the original.