Managing Webhooks in Portal¶
Use Business Settings → Developers → Webhooks to manage webhook subscriptions for your merchant account. Prepare your receiving endpoint before creating a webhook; see Receiving Events for the HTTP request and acknowledgment requirements.
Open the Webhooks section¶
Open Business Settings, select Developers, and open Webhooks. This section lists the webhook subscriptions configured for the account.
Create a webhook¶
Select Create Webhook and complete the configuration.
The following screenshot shows the earlier form, including legacy token expiration. It is not a preview of the updated payload v2 secret controls.
| Setting | What to enter or select |
|---|---|
| Endpoint URL | The HTTPS endpoint in your application that will receive webhook requests. |
| Description | A label or description that helps you recognize the purpose of the subscription. |
| Payload version | Voluntarily select the payload format your endpoint supports and that is available for your integration. Payload v2 requires HMAC verification. See the reference for versions 1 and 2. |
| Events | The notifications you want the subscription to receive. Select at least one event. The legacy Sale subscription groups transaction notifications; in version 2, Sale covers only that endpoint, so select other sale events individually when needed. |
| Status | Active enables the subscription; Inactive leaves it disabled. The creation form starts with Inactive selected. |
| Attempts | The maximum total number of delivery attempts, from 1 to 10, including the initial request. 1 means no retries. Higher values allow retries for failures eligible under the delivery policy. |
| Token expiration (payload v1 only) | The expiration date carried by the legacy JWT token. This is not a scheduled deactivation date for the webhook. Payload v2 has no expiration field. |
Token expiration does not disable the subscription
For payload v1, reaching the token expiration date does not automatically change the webhook to Inactive or stop deliveries. Manage the subscription through its Status setting.
Save and store the credential¶
Review the endpoint URL, payload version, events, status, and attempt limit, then select Create Webhook.
After successful creation, copy the generated credential and store it securely for the server that receives your webhooks. Payload v1 retains its legacy JWT token. Payload v2 uses a cryptographically random opaque secret generated from 32 random bytes with a whsec_ prefix, with no JWT claims or expiration. Treat it as a credential: keep it out of client-side code, screenshots, and application logs.
Configure webhook authentication for your integration before enabling the subscription. If your receiver is not ready, keep the subscription Inactive while you complete the setup.
Regenerate a payload v2 secret¶
Use manual secret regeneration when a replacement is needed. Regeneration replaces the secret immediately, with no automatic rotation or dual-secret grace period. Coordinate the change with your receiving application; requests signed with the replacement secret require the updated receiver configuration. The v2 regeneration flow does not ask for an expiration date.
Move from payload v1 to v2¶
An existing subscription cannot change its payload version through editing; changes in either direction are rejected. To opt in to v2, prepare your receiver for the v2 payload and HMAC verification, then create a separate payload v2 subscription and securely configure its new secret. Select the required v2 events individually. Coordinate activation and deactivation of the old subscription to avoid duplicate business processing or gaps in notification coverage. There is no automatic subscription migration.
Review an existing subscription¶
Return to the Webhooks list to review the configuration and use the subscription's editing controls when changes are needed. Check the endpoint, selected events, status, and attempt limit before saving changes.
For payload examples, use the webhook reference. To prepare your receiver and handle repeated notifications, follow Receiving Events.
Delivery alert email¶
Enter one optional email address in Webhook alert recipient and select Save recipient in the Webhooks settings. Saving a recipient does not enable the API alert service; an enabled service can process pending alerts after a recipient is configured. Leave it empty and save to remove the recipient; no business or payer email is used as a fallback. See Webhook Delivery Alerts for the schedule and investigation steps.