Webhook authentication and delivery

HMAC signature verification

Every webhook delivery includes an HMAC-SHA256 signature so you can verify the request came from Tideflow and was not tampered with.

Signature algorithm

1. Tideflow concatenates the timestamp and the raw JSON body: {timestamp}.{raw body}
2. This string is signed with your endpoint's signing secret using HMAC-SHA256.
3. The result is sent in the X-Tideflow-Signature header as sha256={hex digest}.

Verification pseudocode

// 1. Extract the timestamp and signature from headers
const timestamp = request.headers["x-tideflow-timestamp"];
const signature = request.headers["x-tideflow-signature"];

// 2. Compute the expected signature
const payload = timestamp + "." + rawRequestBody;
const expected = "sha256=" + hmacSha256(signingSecret, payload);

// 3. Compare using a timing-safe function
if (!timingSafeEqual(signature, expected)) {
  return respond(401);
}

Request headers

Every webhook delivery includes these headers:

Delivery semantics

Success criteria

Tideflow considers a delivery successful when your endpoint returns an HTTP status code in the 200–299 range. Any other status triggers a retry.

Timeout

Your endpoint must respond within 8 seconds. If it does not, the delivery is treated as failed for that attempt and retried according to the retry schedule.

Retry schedule

Failed deliveries are retried up to three times total:

After three failed attempts, the delivery is permanently marked as failed.

Idempotency

Use the X-Tideflow-Delivery-Id header to deduplicate deliveries on your side. Tideflow guarantees that each event is enqueued once per endpoint, but retries may cause your endpoint to receive the same delivery more than once.

Security considerations

SSRF protection

Tideflow validates that webhook URLs resolve to public IP addresses before sending. Private, loopback, and link-local addresses are blocked. Redirects are not followed.

Signing secret storage

Your signing secret is encrypted at rest in the Tideflow database. It is only decrypted at delivery time to compute the signature.

Best practices

• Always verify the HMAC signature before processing a delivery.
• Use timing-safe comparison to prevent timing attacks on signature verification.
• Respond with a 2xx status as quickly as possible. Do heavy processing asynchronously.
• Store the raw payload before doing any processing so you can replay events if needed.
• Check the X-Tideflow-Timestamp header and reject deliveries with timestamps older than five minutes to prevent replay attacks.