Skip to main content
Webhooks allow the Method API to notify your application when certain events occur. To receive Webhook notifications, create a Webhook by registering a URL pointing to your application where triggered events should be sent to. This URL is where Method will send event information in an HTTPS POST request.

Handling webhooks

A Webhook event is considered successfully delivered when the corresponding URL endpoint responds with a 2xx 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 a 2xx within 5 seconds (the delivery is retried).
Deduplicate retries
Every delivery includes a method-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
The method-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.
Process webhooks idempotently: fetch the referenced resource and upsert your local state, so handling the same change twice has no effect.
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 status is set to requires_attention and it continues to receive events.
  • Otherwise, its status is set to disabled and no further events are delivered until the Webhook is reactivated.
In both cases an error is set on the Webhook object with details about the failure.
Monitor your Webhook endpoint’s health to avoid exceeding the 40% failure threshold. Even intermittent failures can accumulate over a 24-hour window and trigger automatic disabling. We recommend responding with a 2xx status code immediately and processing webhook data asynchronously.
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

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.
The token for request validation will be sent as a base64-encoded string in the Authorization header of the webhook. You can verify the request originated from Method by base64-encoding your auth_token and comparing it to the incoming header value to ensure the integrity of the event.
If you provide an 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.
The timestamp is always included in the method-webhook-timestamp header, even if no hmac_secret is provided.

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 the Authorization 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.
Once your team is provisioned, configure your endpoint to request and verify the client certificate Method presents. Your Method representative will supply the certificate details and the issuing CA chain for your trust store. For client-certificate authentication on requests your application makes to the Method API, see Mutual TLS (mTLS).

Webhook Objects

Webhook event object

A payment webhook without an event record can have this body:

Webhook Event Types