Handling webhooks
A Webhook event is considered successfully delivered when the corresponding URL endpoint responds with a2xx HTTP status code
within 5 seconds.
If the criteria is not met, Method will reattempt 4 more times
with each new attempt being delayed according to an exponential backoff
algorithm, where the delay period between each attempt exponentially increases.
Handling duplicate deliveries
Webhook delivery is at-least-once: the same event can occasionally be delivered more than once. This happens, for example, when your endpoint processes an event but does not respond with a2xx within 5 seconds (the delivery is retried).
Deduplicate retries
Every delivery includes amethod-webhook-delivery-id HTTP header that identifies one
delivery to one webhook registration. The value stays the same across retries of that
delivery. Record each processed delivery ID and skip any delivery whose ID you have
already processed.
Deduplicate across webhook registrations
Themethod-webhook-change-id HTTP header identifies one underlying resource change.
Deliveries of the same change to different webhook registrations share this value,
including retries. Use it to deduplicate the same change across registrations, such as
when migrating between webhook endpoints. Record processed change IDs in a store shared
by the endpoints that must deduplicate against each other.
For example, if both an old and a new registration receive the same payment change:
These illustrative deliveries represent one change. The same change ID with different
webhook_id values shows that multiple registrations received it. A later change to the
same payment has a different change ID.
Deliveries created before change IDs were introduced can omit
method-webhook-change-id. The delivery ID still identifies retries to one
registration, but cannot identify the same change across different registrations.The
id field in the request body is the ID of the resource that changed, not a unique
event identifier; two different changes to the same resource share it. The body’s
event field can be null, so it is not a reliable deduplication key for all webhooks.
Use the delivery ID for retries to one registration, or the change ID to deduplicate
across registrations.Automatic disabling
Method automatically changes a Webhook’s status when a delivery fails 5 times (the initial attempt and all retries) and more than 40% of the Webhook’s delivery attempts within the rolling 24-hour window have failed. The resulting status depends on your team’s grace period:- If the Webhook is within a grace period configured for your team (measured from the
Webhook’s creation), its
statusis set torequires_attentionand it continues to receive events. - Otherwise, its
statusis set todisabledand no further events are delivered until the Webhook is reactivated.
error is set on the Webhook object with details about the failure.
To reactivate a disabled Webhook, use the Update a Webhook
endpoint to set its status back to active. Before reactivating, ensure the underlying
issue has been resolved to prevent the Webhook from being disabled again.
Authentication
Webhook Request Validation
Webhook Request Validation
We use the
auth_token and hmac_secret you provide to enable webhook authentication.
There are 2 application-layer ways to authenticate an incoming request, described below.
Teams provisioned for webhook mTLS can additionally verify the delivery at the transport
layer, using the client certificate Method presents during the TLS handshake. See
Mutual TLS for webhook delivery.2. HMAC Verification
2. HMAC Verification
If you provide an The timestamp is always included in the
hmac_secret when registering your webhook, Method will include a method-webhook-signature header in every request. This is an HMAC-SHA256 digest created using the hmac_secret as the shared secret, and computed over the string timestamp:payload, where timestamp is the value from the method-webhook-timestamp (UNIX timestamp in seconds) header (which is always included, even if no hmac_secret is provided) and payload is the raw request body.
Checking for the timestamp freshness (5 min window) is optional, but recommended.method-webhook-timestamp header, even if no hmac_secret is provided.Example: Minimal Express Server for Verifying Webhooks
Example: Minimal Express Server for Verifying Webhooks
Mutual TLS for webhook delivery
Method can present a client certificate during the TLS handshake when delivering events to your endpoint. This lets your endpoint verify that the connection originates from Method at the transport layer, in addition to theAuthorization header and HMAC signature checks described above.
Webhook mTLS is optional and opt-in, and must be provisioned per team. Teams
that are not provisioned are unaffected: Method continues to deliver webhooks over
standard TLS with no change to existing endpoints. To enable it, contact your
Method representative.