Skip to main content
Use webhooks as the server-side signal that an order or customer subscription changed, or that an order was refunded. A browser success page is useful for the buyer, but it is not a reliable fulfillment trigger.

​
Set up an endpoint

1

Open Developer settings

In the Business account menu, open Developers, then select Webhooks.
2

Add an HTTPS endpoint

Enter the public HTTPS URL that should receive the selected commerce events.
3

Store the signing information

Cache the published Ed25519 public key in your server-side configuration. You may also retain the endpoint ID for configuration tracking. Neither value is a signing secret.
4

Verify every request

Verify the signature against the raw request body before parsing or acting on the event.

​
Fulfillment rules

  • Route behavior by event type.
  • Use the webhook-id header as the delivery idempotency key.
  • Compare amount, currency, product, and merchant reference with your own records.
  • Update local subscription state from subscription.* events; a scheduled period-end cancellation arrives as subscription.updated, while the final stop arrives as subscription.ended.
  • Revoke what an order granted when refund.succeeded arrives with fullyRefunded: true. Each refund sends its own event. A partial refund (fullyRefunded: false) is your own policy call; most merchants keep access.
  • An endpoint with no event selection receives all events, including refund.*. Return a 2xx for event types you do not handle.
  • refund.failed means a refund was rejected or declined and nothing was refunded. Keep the customer’s access; clear any “refund requested” state you show.
  • Return a successful response quickly and move slow work to a queue.
  • Accept retries and out-of-order delivery.
  • Never move a locally paid order back to pending because an older event arrives.
Never log signatures, API keys, full customer payment details, passport images, or payout account details.

API webhook reference

Review the public key, signature contract, payload, retries, and idempotency rules.

Customers & subscriptions

Understand subscription status, scheduled cancellation, and renewal orders.