Verifying Webhook Signatures

Every webhook Coinflow sends includes a Coinflow-Signature header containing an HMAC-SHA256 signature of the request body. You can use this signature to verify that a webhook was sent by Coinflow and that its payload has not been tampered with.

This is an alternative to the Authorization header approach which should be used in the case of an overriden authorization header.

How It Works

When Coinflow sends a webhook, it signs the JSON body using your Webhook Validation Key and attaches the signature in the Coinflow-Signature header. The header has this format:

Coinflow-Signature: t=1717012345,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Component	Description
`t`	Unix timestamp (seconds) of when the signature was generated
`v1`	HMAC-SHA256 hex digest of the signed payload

The signed payload is the timestamp and the raw JSON body joined by a dot: {timestamp}.{body}.

Verifying the Signature

To verify a webhook signature:

Extract the t and v1 values from the Coinflow-Signature header
Reconstruct the signed payload: {t}.{raw request body}
Compute the HMAC-SHA256 of the signed payload using your Webhook Validation Key
Compare your computed signature to the v1 value using a timing-safe comparison

Node.js / TypeScript

1 import crypto from 'node:crypto';
2 
3 function verifyWebhookSignature({
4   signatureHeader,
5   payload,
6   secret,
7 }: {
8   signatureHeader: string;
9   payload: string;
10   secret: string;
11 }): boolean {
12   const parts = signatureHeader.split(',');
13   let timestamp: string | undefined;
14   let signature: string | undefined;
15 
16   for (const part of parts) {
17     const [key, value] = part.split('=', 2);
18     if (key === 't') timestamp = value;
19     else if (key === 'v1') signature = value;
20   }
21 
22   if (!timestamp || !signature) {
23     throw new Error('Invalid Coinflow-Signature header');
24   }
25 
26   const signedPayload = `${timestamp}.${payload}`;
27   const expected = crypto
28     .createHmac('sha256', secret)
29     .update(signedPayload)
30     .digest('hex');
31 
32   return crypto.timingSafeEqual(
33     Buffer.from(signature),
34     Buffer.from(expected)
35   );
36 }

Usage in an Express route:

1 app.post('/coinflow-webhook', (req, res) => {
2   const signatureHeader = req.headers['coinflow-signature'] as string;
3   const rawBody = req.body; // Must be the raw string body, not parsed JSON
4 
5   const isValid = verifyWebhookSignature({
6     signatureHeader,
7     payload: rawBody,
8     secret: process.env.COINFLOW_VALIDATION_KEY!,
9   });
10 
11   if (!isValid) {
12     return res.status(401).send('Invalid signature');
13   }
14 
15   // Process the webhook
16   const event = JSON.parse(rawBody);
17   handleEvent(event);
18 
19   res.sendStatus(200);
20 });

You must verify the signature against the raw request body string, not a parsed-and-re-serialized JSON object. Re-serializing can change whitespace or key order, which will cause verification to fail.

Python

1 import hmac
2 import hashlib
3 
4 def verify_webhook_signature(signature_header: str, payload: str, secret: str) -> bool:
5     parts = dict(p.split("=", 1) for p in signature_header.split(","))
6     timestamp = parts.get("t")
7     signature = parts.get("v1")
8 
9     if not timestamp or not signature:
10         raise ValueError("Invalid Coinflow-Signature header")
11 
12     signed_payload = f"{timestamp}.{payload}"
13     expected = hmac.new(
14         secret.encode(), signed_payload.encode(), hashlib.sha256
15     ).hexdigest()
16 
17     return hmac.compare_digest(signature, expected)

Where to Find Your Webhook Validation Key

Your Webhook Validation Key is available in the Coinflow Admin Dashboard under Developers → Webhooks. See Configuring Webhooks for setup instructions.

1	import crypto from 'node:crypto';
2
3	function verifyWebhookSignature({
4	signatureHeader,
5	payload,
6	secret,
7	}: {
8	signatureHeader: string;
9	payload: string;
10	secret: string;
11	}): boolean {
12	const parts = signatureHeader.split(',');
13	let timestamp: string \| undefined;
14	let signature: string \| undefined;
15
16	for (const part of parts) {
17	const [key, value] = part.split('=', 2);
18	if (key === 't') timestamp = value;
19	else if (key === 'v1') signature = value;
20	}
21
22	if (!timestamp \|\| !signature) {
23	throw new Error('Invalid Coinflow-Signature header');
24	}
25
26	const signedPayload = `${timestamp}.${payload}`;
27	const expected = crypto
28	.createHmac('sha256', secret)
29	.update(signedPayload)
30	.digest('hex');
31
32	return crypto.timingSafeEqual(
33	Buffer.from(signature),
34	Buffer.from(expected)
35	);
36	}

1	app.post('/coinflow-webhook', (req, res) => {
2	const signatureHeader = req.headers['coinflow-signature'] as string;
3	const rawBody = req.body; // Must be the raw string body, not parsed JSON
4
5	const isValid = verifyWebhookSignature({
6	signatureHeader,
7	payload: rawBody,
8	secret: process.env.COINFLOW_VALIDATION_KEY!,
9	});
10
11	if (!isValid) {
12	return res.status(401).send('Invalid signature');
13	}
14
15	// Process the webhook
16	const event = JSON.parse(rawBody);
17	handleEvent(event);
18
19	res.sendStatus(200);
20	});

1	import hmac
2	import hashlib
3
4	def verify_webhook_signature(signature_header: str, payload: str, secret: str) -> bool:
5	parts = dict(p.split("=", 1) for p in signature_header.split(","))
6	timestamp = parts.get("t")
7	signature = parts.get("v1")
8
9	if not timestamp or not signature:
10	raise ValueError("Invalid Coinflow-Signature header")
11
12	signed_payload = f"{timestamp}.{payload}"
13	expected = hmac.new(
14	secret.encode(), signed_payload.encode(), hashlib.sha256
15	).hexdigest()
16
17	return hmac.compare_digest(signature, expected)