Generic HMAC

Most providers sign webhooks with an HMAC of the body, sent in a header. The hmac verification method describes such a scheme with a few fields, so Ricochet can check senders it has no preset for.

Field	Meaning	Default
header	The header holding the signature. Required.
algorithm	sha1, sha256 or sha512.	sha256
encoding	hex (any case) or base64.	hex
prefix	Text before the signature in the header, such as sha256=.	none
signed_content	What is signed: {body}, or a template with {timestamp}, such as {timestamp}.{body}.	{body}
timestamp_header	The header holding {timestamp}. Required when signed_content uses it.
tolerance_seconds	How far that timestamp may be from now.	300

The source’s secret is the HMAC key, as the provider gives it. If the header carries several space-separated signatures, any one that matches passes.

Examples

A provider that sends X-Signature: <hex HMAC-SHA256 of the body>, as the dashboard’s Generic HMAC sender sets up:

{ "method": "hmac", "header": "x-signature" }

A provider that sends X-Hub-Signature: sha1=<hex>:

{ "method": "hmac", "header": "x-hub-signature", "algorithm": "sha1", "prefix": "sha1=" }

A provider that signs <timestamp>.<body> in base64, with the timestamp in its own header:

{
  "method": "hmac",
  "header": "x-webhook-signature",
  "encoding": "base64",
  "signed_content": "{timestamp}.{body}",
  "timestamp_header": "x-webhook-timestamp"
}

Testing it

Send a test event from the source’s page in the dashboard: Ricochet signs it with the source’s newest secret using these settings, so it verifies. If a real request fails, its event (with the source set to quarantine failures) shows the reason, and the signature debugger shows the expected and received signatures step by step.