Webhook Signature Verification: Is This Business Event Genuine?
Start with the short answer ↓
Before a webhook creates work in another system, verify its origin using the provider's documented method. Then check the account, event type, current business state and duplicate history. A valid signature is not blanket permission to act.
Prepared with AI assistance. These are practical scoping recommendations; examples are illustrative, not client results.
A plausible message is not proof of its origin
A service-desk notification arrives and asks an integration to create a dispatch task. The JSON looks familiar and contains the expected customer reference. That does not establish who sent it. Define how the receiving application distinguishes a verified provider delivery from an arbitrary request before connecting that request to operational writes. This is an illustrative design exercise, not a customer incident or a delivered-connector claim.
Keep three decisions separate: whether the delivery passes the provider's authenticity check, whether this event is authorized for this workflow, and whether the resulting business work was completed. A successful check at one boundary does not automatically answer the other two.
Choose events or scheduled synchronization for the actual workflow
Use the provider's verification contract
GitHub's webhook guidance describes validating a signature generated from the webhook secret and payload before processing a delivery. Stripe's signature-error guidance requires the original request body, the signature header and the correct endpoint secret. These are provider-specific examples, not interchangeable header names or a universal algorithm.
Ask which supported library or documented verification path the implementation will use and where it runs in the request handler. For Stripe's documented check, changing the body before verification can invalidate the result. Include proxies and framework body handling in the review. A familiar event label or a header containing the provider's name is not the verification itself.
Write down what each check actually proves
Our proposed worksheet makes the remaining business decision visible instead of treating every accepted delivery as an approved action. Fill it in for one actual event and destination before extending it to more workflows.
| Check | What it helps establish | What still needs a decision |
|---|---|---|
| Provider verification succeeds | The received delivery passes the configured provider's authenticity check. | Whether the account, event and destination belong to the intended business workflow. |
| Event type is in the approved scope | This kind of event is eligible for handling. | Whether the current record state allows the proposed change. |
| Original event or action reference was checked | The system can identify prior handling or an unresolved attempt. | Whether to skip, reconcile or perform the permitted next step. |
| Destination record is verified | The intended business result can be inspected. | Whether any exception or human review remains open. |
Separate a repeated delivery from permission to repeat an action
Bind the event to the right account and state
In the illustrative dispatch workflow, a verified event for one service account must not create work in another customer's environment. Configure the expected provider, environment and account mapping on the receiving side. Do not let an arbitrary destination URL or an unrelated identifier in incoming content expand the workflow's permissions.
A genuine event can also arrive after the underlying case has changed. Suppose the dispatch task was already completed manually. The event should reach the agreed reconciliation path rather than silently create another task. Use the event and business-action references supported by the actual systems. Where a provider documents signed timing or freshness checks, implement that contract; do not assume that every signature automatically expires.
Keep secrets and untrusted text out of the wrong places
Name who owns the webhook configuration and how an authorized operator handles a secret change. Keep signing secrets out of source control, public pages, URLs and diagnostic output. Investigate a mismatch using redacted configuration references and the documented environment, not by pasting production secrets into a project brief. A configuration change needs its own authorized process.
Authenticating a delivery does not turn every field into trusted operating policy. If an event includes a customer-written note that an AI assistant later reads, that note remains customer content. It cannot grant access to other records or override a required approval. Preserve the distinction between a verified transport and the authority of the text carried inside it.
Keep incoming messages separate from AI operating instructions
Test rejection, acceptance and recovery separately
Use an isolated environment with production sending and consequential writes disabled. Prepare a genuine test delivery, a changed payload, a missing or incorrect signature, a wrong environment or endpoint configuration, a duplicate valid event and an event whose business case has already been completed. Add provider-specific timing tests where the documented mechanism supports them.
For each case, state the expected verification result, allowed downstream action, visible exception and owner. Invalid deliveries must not cause the protected business write; valid in-scope work should still proceed through its normal checks. Record the provider contract and test outcome with the release. This worksheet is a scoping aid, not a full security assessment or a guarantee that every webhook integration is safe.
Primary references
The guidance above is AgenticShip's proposed approach. These references provide technical background for the relevant recommendations.