Using Webhooks
Request Headers
When Frontitude sends a webhook event, it includes three essential headers:
webhook-id: An ID that uniquely identifies each request. You can cross-reference this identifier with delivery history within Frontitude.
webhook-timestamp: A Unix timestamp indicating when the request was made. This timestamp is included in the signature to guard against replay attacks.
webhook-signature: A list of signatures (HMAC-SHA256) created using your workspace's webhook signing key and will be used to validate the event’s authenticity. It is composed of space delimited signatures and their corresponding version identifiers. For example: “v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= v2,MzJsNDk4MzI0K2VvdSMjMTEjQEBAQDEyMzMzMzEyMwo=”. Make sure to remove the version prefix and delimiter (e.g. v1,) before verifying the signature.
Request Validation and Processing
Frontitude expects all webhook consumers to respond with a status code between 200 and 299 within a reasonable time-frame (up to 15s) to indicate successful event processing.
For enhanced security, follow these actions before processing a webhook event and issuing a success response:
Validate the signature included in the webhook-signature header. Concatenate the webhook ID, timestamp, and a string representation of the request body into a single string, separated by periods. Use HMAC-SHA256 to sign this value with your signing key and compare it against the header's signature list.
(Optional) Validate event's timestamp against system's timestamp to make sure it's within tolerance in order to prevent timestamp/replay attacks.
(Optional) Ensure idempotence by tracking request IDs (by using the webhook-id header) in a persistent data store and ensuring that new events have not been processed before.
Our code sample below will help you get started quickly.
Error Handling
If Frontitude receives an error response from your server, it will make additional attempts to send the event based on a retry schedule with exponential backoff.
The schedule (where each period is started following the failure of the preceding attempt):
Immediately
5 seconds
5 minutes
30 minutes
2 hours
5 hours
10 hours
10 hours (in addition to the previous)
After the conclusion of the above attempts the event will be marked as Failed for this endpoint. If all attempts to a specific endpoint fail for a period of 5 days, the endpoint will be disabled.
Last updated