Webhook Management

Retrieve the webhook endpoint configuration: URL, active flag, event subscription and delivery health. The signing secret is never returned, has_secret only reports that one exists. Returns 404 until an endpoint is created with PUT /api/v1/webhook.

Merchant API keys read their own configuration. Partner API keys must include merchant_id for a linked merchant.

Register the HTTPS endpoint that receives signed webhook events, or update it in place. On first creation the response includes the plaintext signing secret exactly once. The secret is stored encrypted and can never be read back, so capture it from that response and store it securely. Updates never return or regenerate the secret.

The URL must use HTTPS on a publicly resolvable host. URLs with embedded credentials, localhost style hosts or private IP addresses are rejected. See the set up webhooks guide for the full walkthrough.

Merchant API keys manage their own endpoint (one per merchant). Partner API keys must include merchant_id for a linked merchant.

Remove the webhook endpoint. Deliveries stop immediately, any event still queued for it is marked failed, and the stored URL and signing secret are erased. Delivery history stays readable through the events endpoints. A new endpoint can be registered afterwards with PUT /api/v1/webhook, which issues a new signing secret. To pause deliveries without losing the configuration, set is_active to false instead.

Merchant API keys delete their own endpoint. Partner API keys must include merchant_id for a linked merchant.

Generate a new signing secret for the endpoint. Rotation is a hard cutover: the old secret stops signing immediately and the new one is returned exactly once in this response, so update your verifier right away. Deliveries retried after rotation are signed with the new secret.

Merchant API keys rotate their own secret. Partner API keys must include merchant_id for a linked merchant.

Send a signed ping event to the endpoint synchronously and report whether the receiver answered with a 2xx status. Use it to verify reachability and signature handling before real events flow. A successful ping verifies the endpoint (it stamps last_success_at and resets the failure streak), which is what unlocks payment-session creation when the webhook readiness gate is enabled. The ping never appears in delivery history and a failed ping persists nothing. A failing receiver still returns HTTP 200 here, check data.success for the outcome. Limited to 10 pings per minute per API key.

Merchant API keys ping their own endpoint. Partner API keys must include merchant_id for a linked merchant.

List recorded webhook events newest first (delivery history). List rows never include the payload snapshot, fetch a single event for that. History depth equals the 30 day retention window, older events are pruned and cannot be listed or replayed.

Merchant API keys list their own events. Partner API keys must include merchant_id for a linked merchant.

Retrieve one event with the stored payload snapshot (exactly what was signed and sent, card data free by construction) and the full delivery attempt trail in chronological order. An event that is not visible to this API key returns 404.

Queue a fresh delivery of the stored event: same event id and payload, a fresh delivery id and an X-Softlemon-Replay: true header so receivers can tell replays from originals. Replaying an already delivered event is allowed, for example when the original was lost. A failing replay never demotes a delivered event. Events older than the 30 day retention window are pruned and cannot be replayed. Limited to 30 replays per minute per API key.