Payiano Webhooks Guide

What are Webhooks?

Webhooks are automated messages sent from Payiano to your server when specific events occur in your account. They allow your system to react in real-time to important activities, such as creating a payment link or completing a checkout. This enables seamless integration and immediate response to user actions, ensuring that your application remains up-to-date with the latest events.

Setting Up Webhooks

To receive webhooks, you need to register webhook URLs where these messages will be sent. You can register up to 10 URLs per merchant account. Each URL can listen for specific event types or all events by using the wildcard *. These URLs can be assigned to different apps or enabled to employee actions within your account. This ensures that the right events trigger the right notifications.

  • Register Webhook URLs: You can register up to 10 URLs per merchant account. Each URL can be configured to listen for specific event types, or you can use the wildcard * to subscribe the URL to all event types.
  • Assign URLs: These webhook URLs can be assigned to different applications or enabled for employee actions within your account. This ensures that the right events trigger the appropriate notifications, providing flexibility in how webhooks are managed and utilized across your system.

How Webhooks Work

When an event such as payment_link.created or checkout.created happens, Payiano sends a POST webhook message to the registered URL. Here’s a detailed look at how this process works:

  • Event Occurrence: An event occurs in your Payiano account, such as the creation of a payment link or the completion of a checkout.
  • Message Delivery: Payiano sends a POST request containing the event details to the registered webhook URL.
  • Acknowledge Receipt: Your server needs to acknowledge receipt of the message by responding with a 2xx status code (such as 200 OK). This indicates that your server has successfully received and processed the webhook.
  • Retry Mechanism: If your server responds with a non-2xx status code, Payiano will retry sending the message multiple times until it receives a 2xx response. This ensures reliable delivery of the event notifications.

Testing Your Webhook Integration

Before deploying your webhook URL to a live environment, it is important to thoroughly test your application integration. This ensures that your system can correctly receive and process webhook events from Payiano.

Use a tool like Ngrok to create a secure tunnel to your local machine. Ngrok provides a public URL that forwards requests to your local development environment. This allows you to test how your local server handles incoming webhook events. You can add that public URL to your webhook URLs and ensure it's assigned to the appropriate applications.

Use Payiano to send a Payment Link and a payment_link.created and checkout.created events will be fired and Payiano will send these test events to your Ngrok public URL, allowing you to observe how your local server processes them. Ensure that your server correctly handles, processes, and responds to those events with the appropriate status codes.

Timeout Settings

To ensure efficient communication and avoid prolonged connection attempts, Payiano sets the following timeout values for webhook delivery:

  • Connection Timeout: The maximum time Payiano will wait to establish a connection to your server is 10 seconds.
  • Request Timeout: The maximum time Payiano will wait for your server to respond after the connection has been established is 20 seconds.

Optimizing Webhook Event Listening

To ensure optimal performance and efficiency, it is essential to configure your webhook URLs to only receive the specific event types that are necessary for your integration. If your integration only needs to know about payment completions and refunds, you should only subscribe to these specific events. Avoid subscribing to all events or unnecessary ones, as this can lead to excessive and irrelevant traffic.

By filtering out unnecessary events, you reduce the load on your server. Handling only the essential events minimizes processing overhead, conserves resources, and enhances your system's performance. This targeted approach ensures your server is not overwhelmed with unneeded data, leading to faster response times and more efficient operations.

Configure your event handler to process incoming webhook events using an asynchronous queue. Instead of processing events immediately and directly within the webhook handler, enqueue the events for later processing. This decouples the receipt of events from their processing, allowing your system to handle spikes in traffic more effectively.

Processing events synchronously can lead to scalability issues. For instance, during peak times such as the beginning of the month when numerous subscriptions renew simultaneously, your server might receive a large volume of webhook deliveries. If your system tries to handle all these events at once, it can overwhelm your endpoint hosts, leading to delays, timeouts, or even crashes.

Monitoring Webhooks

The List Webhook Event Attempts endpoint provides a detailed log of all attempts made to deliver a specific webhook event. Each event may have multiple attempts if initial deliveries fail. This log includes information such as the status, response code, response body, and timestamps for each attempt. This visibility helps you understand the delivery history and troubleshoot any issues affecting successful notification delivery.

Troubleshooting

If you experience issues with receiving webhooks, consider the following steps to diagnose and resolve the problems:

  • Server Accessibility: Ensure your server is reachable from the public internet. If your server is behind a firewall or in a private network, make sure it allows incoming connections from Payiano’s servers.
  • Firewall Settings: Check that your firewall allows incoming HTTP requests on the appropriate port. Ensure that the port you are using for your webhook endpoint is open and accessible.
  • Endpoint Configuration: Verify that your endpoint is correctly configured to handle POST HTTP requests. Ensure your server is set up to process incoming webhook requests properly and that it returns the appropriate 2xx status code upon successful receipt.