Webhook overview

Webhooks notify your backend when a payment or withdrawal changes without requiring constant polling. Treat them as prompts to reconcile your own record with SkyPay, not as browser notifications.

Register an endpoint

1. Open Settings → Webhooks in the merchant dashboard.
2. Select Sandbox or Live.
3. Enter the HTTPS URL that receives events. Sandbox also permits HTTP for local testing.
4. Select the events you need. An empty selection subscribes to every supported event.
5. Save the signing secret immediately; it is shown once.
6. Send a test event and inspect the delivery log.

Each endpoint receives events only from its configured environment. A Sandbox event is never delivered to a Live endpoint.

This merchant-facing endpoint is separate from SkyPay's inbound provider routes. Paystack and Payaza send Sandbox and Live events to different SkyPay URLs, and SkyPay verifies them with environment-specific secrets before updating a payment. Your integration receives only the normalized SkyPay event.

Handler responsibilities

1. Preserve the raw request bytes.
2. Verify X-SkyPay-Signature before parsing or trusting the body.
3. Deduplicate using X-SkyPay-Delivery or your stored event reference.
4. Persist the accepted event and return a 2xx response quickly.
5. Process slow business actions asynchronously.
6. Retrieve the latest payment status before irreversible fulfilment.

SkyPay retries non-2xx responses and connection failures up to five attempts. See retry behavior and signature verification.