An integration receives a well-formed message saying an order changed or a payment completed. The endpoint returns success, and the business system updates a record. But did the message really come from the expected provider? A familiar-looking payload and a successful HTTP response do not answer that question.

A webhook is an incoming request that notifies software about an event. Before that notification can trigger a business action, the receiving system needs an appropriate verification process. This guide explains the questions a business owner should ask its integration developer; the actual implementation must follow the relevant provider's protocol.

The artwork is an editorial concept of an authenticated-message checkpoint, not a provider interface or a real integration diagram.

Start with the provider's verification method

HTTPS protects the connection in transit. It does not, on its own, establish that every request reaching a public endpoint came from your provider. Use the provider's documented authentication or signature mechanism and the supported library where available.

For example, GitHub documents webhook validation using a configured secret and the X-Hub-Signature-256 header. Its guidance calls for a timing-safe comparison. Other providers can sign different inputs or use different headers, so a working GitHub verifier is not automatically a working verifier for another service.

Keep the signed payload intact

Stripe's signature troubleshooting guidance explains that verification uses the original request body, signature header and endpoint secret. Middleware that changes the body before verification can break that check. The endpoint secret for a CLI-forwarded test is also different from a Dashboard-managed endpoint secret.

Ask your developer to explain where verification happens in the request pipeline. A proxy, framework upgrade or newly added JSON parser can change what the verification code receives. The solution is to preserve the required input and use the correct environment-specific secret, not disable the check to make errors disappear.

Keep signing secrets in an appropriate secret store, with controlled access and a rotation plan. Do not put them in source control, browser code, support screenshots or public request logs.

Separate authenticity from permission to change a record

A valid signature establishes the result of the provider-specific verification check. It does not mean the application should perform every action described by every event. The integration still needs to recognise supported event types and associate them with the correct business account and resource.

In an illustrative order workflow, the developer might verify the event, identify the existing order and confirm the relevant provider-side state before applying an allowed transition. That is a design example, not a universal payment-processing recipe. The checks depend on the provider, event format and business rules.

A scoped API development and integration review should cover both boundaries: who sent the notification and which authorised business change it can trigger. Request a Webhook Verification Review if your current integration cannot explain those boundaries clearly.

Plan for freshness and repeated delivery

Stripe documents a signed timestamp and freshness tolerance to reduce replay risk. That requires an accurate server clock. Timestamp checks are protocol-specific; do not assume every provider includes the same signed fields.

Freshness checks do not replace duplicate handling. GitHub recommends tracking its delivery identifier and notes that a requested redelivery retains the original identifier. Your application needs a record of completed work and a safe rule for recognising legitimate repeat notifications.

Keep this distinction visible in the brief: verification addresses whether a delivery passes the expected trust checks; safe retry and duplicate handling addresses whether an accepted notification can repeat a business action. Neither is a substitute for the other.

Use an acceptance checklist with negative tests

A happy-path demonstration is insufficient for an endpoint that accepts external requests. Agree tests in a non-production or otherwise authorised environment, using controlled sample data:

  • Valid delivery: the correct provider and environment produce the expected accepted work item.
  • Changed body: modifying a signed request without a matching signature does not trigger a business action.
  • Wrong or missing signature: the endpoint rejects the request according to the provider's handling requirements.
  • Wrong environment: a test delivery does not silently authenticate using an unrelated production configuration.
  • Expired delivery: where the protocol supports a signed freshness check, an old request is handled as specified.
  • Legitimate repeat: redelivery does not create a second order, entitlement or CRM record.
  • Unexpected event: an otherwise valid but unsupported notification cannot invoke an unintended workflow.

Record the expected business effect as well as the HTTP response. Do not replay real customer events against production merely to prove a checklist item.

Acknowledge receipt without losing the work

Avoid performing a long business workflow while the provider waits for an HTTP response. Use the relevant provider's delivery contract and a durable intake design where appropriate. Acknowledge accepted work promptly, then process it through a monitored path. Returning success before the request is safely retained can conceal a loss instead of solving a timeout.

For operational reporting, distinguish received requests, verification failures, accepted events, queued work and completed business updates. An endpoint's success response is not evidence that the final CRM or accounting update completed.

Include verification in change control

Repeat the relevant acceptance checks when the hosting route, middleware, provider configuration or signing secret changes. Keep a named owner for alerts and failed work, with a record of how to investigate without exposing secrets or unnecessary customer information.

Ask for handover documentation that identifies the provider, endpoint, environment, verification method, approved event types, secret owner and review responsibilities. That is more useful than a single screenshot showing a successful test.

Request a Webhook Verification Review

Bring the provider name, the business workflow and a description of the current issue to an ITZ API integration review. We can scope verification, event handling and operational handover around the systems involved. Request a Webhook Verification Review without sharing signing secrets, access tokens or customer payloads in the enquiry form.