Skip to main content
Use webhooks as the server-side signal that an order or customer subscription changed. 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 profile 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.
  • 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.