All articles Bot detection

Signed webhook automation: verify, retry, log

Signed webhook automation: verify, retry, log

Webhook automation is the part of a risk stack that turns a decision into an action somewhere else: a blocked signup opens a ticket, a step-up checkout pings Slack, an allow lands in the CRM with the reason attached. Delivering an HTTP POST is easy. Making that POST trustworthy when the receiver is another service, on another network, run by another team, is the actual work.

Most teams find the gap after the first bad week — a replayed payload, an action applied twice, or a run nobody can explain a month later. The fix is unglamorous and cheap: sign every request, verify before you parse, make retries safe by design, and keep a run log with the identifiers that let you rebuild the sequence.

The four steps below are what we recommend to teams sending Prynt decisions into their own systems. They apply whether the sender is Prynt Automate or a service you wrote yourself.

What a signature proves, and what it does not

An HMAC signature proves two things: the body arrived intact, and the sender knew the shared secret. That is all. It does not prove the action was authorized, it does not encrypt anything, and it does not stop the same event from being delivered twice.

Design around that limit:

  • Sign the raw bytes. Compute HMAC-SHA256 over timestamp + "." + rawBody and send the hex digest in a header. Serialize the body once and sign exactly what you send; re-serializing JSON on the receiver changes whitespace and breaks the digest.
  • Put the timestamp inside the signed message. Without it, a captured request stays valid forever.
  • Keep the secret out of the payload and out of logs. Rotate it on a schedule you can state out loud, and accept two secrets while you rotate.
  • Return 2xx only when you accepted the event, not when it merely passed verification. A 200 tells the sender to stop retrying.

If you need the decision itself to be defensible, authorization belongs in your policy code, not in the signature. Prynt never blocks on its own: it returns allow, step-up or block with a reason code, and your code decides. See how those decisions are shaped at https://pryntid.com/platform.

Verify before you parse

The order matters: read the raw body, check the timestamp window, compute the digest, compare in constant time, and only then parse JSON. A 400 on a malformed body is fine; parsing first and inferring later is not.

import crypto from "node:crypto";

export function verify(rawBody, headers, secret, now = Date.now()) {
  const ts = Number(headers["x-prynt-timestamp"]);
  if (!Number.isFinite(ts) || Math.abs(now / 1000 - ts) > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");

  const received = headers["x-prynt-signature"] ?? "";
  if (received.length !== expected.length) return false;

  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}

Two details cause most verification bugs. timingSafeEqual throws when the buffers differ in length, so compare lengths first. And the five-minute window above is a policy choice — pick a number your clock skew tolerates and your security review accepts, then write it down.

Retry safely

Retries are a delivery feature, not a failure. What breaks systems is applying the same event twice.

Make the handler idempotent. Take an event id (Prynt exposes {{trigger.requestId}} in Automate templates), write it to a unique index before doing work, and return 2xx on a repeat. Do the side effect in the same transaction as the insert, or you have invented a race.

Separate retryable from terminal. Timeouts, 429 and 5xx deserve exponential backoff with jitter. 400, 401 and 422 will fail identically forever; retrying them only burns executions.

Do not assume order. Two events fired seconds apart can arrive reversed. If your state machine cares, carry the decision timestamp and drop anything older than the state you already hold.

Acknowledge fast, process slow. Return 2xx after storing the event, then handle it in a worker. Long synchronous handlers time out and trigger retries you did not want.

Keep a run log you can defend

When someone asks why one account was flagged on one afternoon, a run log answers in seconds instead of an hour of log archaeology. Record one row per attempt: event id and request id, decision and risk score, visitor id, target URL, signature result, HTTP status, attempt number, latency, template version and a capped response snippet.

Three rules keep the log useful:

  • Store the payload you actually sent, not the payload you meant to send. Templates change; the log must not.
  • Cap response bodies at a few hundred bytes. You need the error, not the document.
  • Link each row to the workflow that produced it, so a template edit is traceable to the executions it affected.

Wire it into your workflow

In Prynt Automate, workflows run from Identify decisions, alerts, page views, custom events, inbound webhooks or a schedule, and the outgoing step is a signed webhook with retries and a run log. Templates use fixed variables — {{trigger.decision}}, {{trigger.riskScore}}, {{trigger.visitorId}}, {{trigger.requestId}}, {{trigger.url}}, {{trigger.reasons | json}}, {{steps.s1.output.text}} — so the payload your receiver verifies stays stable across edits.

A common shape: a block on checkout goes to Slack with the reason array, an allow goes to your order service using the request id as the idempotency key, and a step-up becomes a CRM task. Automate is $39 per 1,000 executions; the receiving side is your code, and the snippet above is enough to start. The payload schema lives in the docs: https://pryntid.com/docs.

For the decision side of the same integration, our payment fraud detection page covers which signals feed an allow, step-up or block at checkout: https://pryntid.com/payment-fraud-detection.

FAQ

Does a signed webhook replace authentication?

No. A signature authenticates the sender and protects integrity in transit. Authorization — whether this action is allowed for this account — stays in your policy code, which is why Prynt returns a decision with a reason code instead of applying the block itself.

How many retries should a sender attempt?

Set a cap and a dead-letter path rather than copying a fixed number. What matters is that terminal errors are not retried, retries use backoff with jitter, and exhausted events land where a person can inspect them.

What belongs in the run log for a compliance review?

Identifiers and the decision, not the customer’s data: event id, request id, decision, reason codes, timestamps, attempt count and outcome. Keep raw payload retention short and documented.

Start with a receiver you trust

Build the workflow once with a verified receiver, an idempotent handler and a queryable log, and every later integration reuses the same pattern. Prynt Automate ships signed webhooks, retries and a run log, and the rest of the suite feeds it decisions from the same account.

Create your account at https://pryntid.com and read the webhook reference at https://pryntid.com/docs.

Try it free

Prynt is device intelligence with a free plan: 5,000 identifications a month, visitor IDs with confidence and bot detection — no credit card. Upgrade to Pro for VPN, proxy, tampering and behavioral signals.

Keep reading