Outbound webhooks are not configured through the S2S API. You register a URL and obtain a signing secret through authenticated profile APIs, separate from API-key authentication used for create-payment.
Prerequisites
Requirement
Details
KYB
Webhook management is only available when onboardingStatus === "KybVerified".
API key created first
The product requires an API key to exist before saving webhook settings.
HTTPS URL
Use a publicly reachable HTTPS endpoint in production (or a tunnel such as ngrok for development).
API surface (profile)
Webhook routes are mounted under the profile router:
Exact routing may include prefixes depending on your gateway; confirm with your integration contact. These handlers expect Firebase-authenticated requests, not the S2S API key flow.
First-time creation returns a signingSecret. Store it in a secrets manager immediately. On update, the existing secret may be returned without rotation unless you call regenerate-secret.
Webhook record status
Delivery requires:
status: active on the webhook document
Valid webhookUrl and signingSecret
Use the status patch endpoint to deactivate temporarily during maintenance.
None (non-2xx is logged; no automatic backoff queue in this codebase)
Recommendation: Respond with 2xx immediately after validating the signature and enqueueing work to your internal queue. Perform heavy work asynchronously.