Webhooks

Webhooks are a crucial component of the Splice API, enabling real-time notifications for payment events. This guide will help you understand how to configure and use webhooks effectively in your integration with Splice.

What are Webhooks?

Webhooks are user-defined HTTP callbacks that are triggered by specific events in a system. In the context of Splice API, webhooks allow your application to receive real-time notifications about payment events, eliminating the need for constant polling.

Configuring Webhooks

When creating your institution account using the /institutions/new endpoint, you'll need to specify two webhook-related fields:

1. send_payment_notif_endpoint: For notifications about outgoing (sent) payments.
2. recv_payment_notif_endpoint: For notifications about incoming (received) payments.

Here's an example of how these fields appear in the API request:

{
  // ... other fields ...
  "recv_payment_notif_endpoint": "https://your-domain.com/webhooks/received-payments",
  "send_payment_notif_endpoint": "https://your-domain.com/webhooks/sent-payments",
  // ... other fields ...
}

Webhook Payload

When a payment event occurs, Splice will send an HTTP POST request to the appropriate webhook endpoint. The payload will contain relevant information about the payment event, such as status of a payment.

Implementing Webhook Endpoints

To properly handle these notifications:

1. Set up endpoints on your server to receive POST requests from Splice.
2. Implement proper security measures, such as verifying the source of the webhook.
3. Design your endpoint to respond quickly (preferably within 5 seconds) to acknowledge receipt of the webhook.

Best Practices for Webhook Handling

1. Implement idempotency: Handle potential duplicate webhook deliveries gracefully.
2. Use a queueing system: Process webhooks asynchronously if your processing is time-consuming.
3. Proper error handling and logging: Implement robust error handling and logging for debugging purposes.
4. Retry mechanism: Consider implementing a retry mechanism on your end in case of temporary failures.

Conclusion

By properly configuring and handling webhooks, you can ensure that your system stays up-to-date with payment activities in real-time. This allows for prompt processing and improved user experience in your integration with the Splice platform.

Next steps

You may proceed to the next section learn more about errors and how to handle them.

Or you can start interacting with our sandbox and exploring the rest of the endpoints here: API Reference

If you have any questions, you can reach out to us on email support@splice.africa or join our Discord server. We are always online and happy to help.