Webhooks
Use webhooks to receive automatic quote updates
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:
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.