AddThisFeature

Inbound Webhook Verification

Accept provider events without letting anyone forge them.

involved Integrations

What it adds

Signature, timestamp, and replay checks on incoming webhooks, with the real work moved off the request.

What your agent is told to do

6
  1. 1

    Verify the signature against the exact raw request body, captured before any JSON parsing or middleware rewriting. Re-serialized JSON produces a different signature and every event fails.

  2. 2

    Compare signatures with a constant-time comparison. A byte-by-byte early exit is measurable.

  3. 3

    Reject requests whose signed timestamp is outside a short tolerance window, and record processed event IDs so a replayed event is a no-op.

  4. 4

    Acknowledge with a 2xx as soon as verification passes and process asynchronously. Providers time out fast and retry, so slow handlers manufacture duplicates.

  5. 5

    Support more than one active signing secret so a rotation does not drop events mid-cutover.

  6. 6

    Do NOT trust any data in the payload beyond the event ID. Fetch the current object from the provider's API before acting on it — payloads arrive out of order and may already be stale.

Edge cases it handles

6
  • Events arrive out of order. An update can land before the create. Handle unknown-object events by fetching, not by failing.
  • The same event will be delivered more than once. Idempotency is not optional; key on the provider's event ID.
  • A malformed or unverifiable body must return an error the provider treats as final, and must be logged with enough context to debug without storing the raw secret.
  • Returning a 5xx makes most providers retry with backoff. Return 2xx for events you deliberately ignore, or you will build an accidental retry storm.
  • Body-size and content-type limits still apply. An unbounded webhook endpoint is a memory exhaustion vector.
  • During secret rotation, verify against both the old and new secret until the old one is retired, then remove it deliberately.

Definition of done

8
  • Signatures are verified against the unmodified raw body using a constant-time comparison.
  • Stale timestamps are rejected and repeated event IDs are processed once.
  • The endpoint acknowledges within the provider's timeout and processes work in the background.
  • Two signing secrets can be valid simultaneously during rotation.
  • Ignored events return a success status rather than triggering retries.
  • Handlers refetch object state rather than trusting payload contents.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.