Best practices for using webhooks

Follow these best practices to ensure your webhooks function seamlessly and securely.

Configure event types

Your webhook endpoint should be configured to receive only those events that are required by your integration. While it is possible to set up your endpoint to listen to all events, doing so will put undue strain on your server and is, therefore, not recommended.

You can add, remove, or change the type of events that your endpoint will receive through the Dashboard or with the API.

Delivery status

If Falu does not quickly receive a 2xx response status code for an event, we mark the event as failed and stop trying to send it to your endpoint.

When your webhook events are not acknowledged, you can check the Event status or Logs under your Dashboard.

View events

When viewing information about your events through the Dashboard (Dashboard>>Developers>>Events), you can also filter for a specific type of event. You can then view when particular events were created or updated and their status. For example, in the figure below, one is checking for all payment.failed events. A description of a specific event, when it was created, and its ID are then given.

View event logs

The Logs section of the dashboard (Dashboard>>Developers>>Logs) gives you a finer granularity when viewing the status of your events. For example, as shown below, you can filter by endpoint or date and view the HTTPS status of the event alongside other information such as its Trace Id and the Falu API version used.

Event handling

Webhook events should be configured and handled correctly to safeguard your integration's business logic.

Handling duplicate events

Occasionally, your webhook endpoints may receive duplicates of the same event. One way of safeguarding against such an occurrence is by making your event processing idempotent. Check the Idempotency guide for more information.

Security

Keeping your endpoints secure is critical to protecting your customers’ information. We provide a number of ways for you to verify that events are coming from Falu.

Receive events with an HTTPS server

If you use an HTTPS URL for your webhook endpoint, Falu first validates that the connection to your server is secure before sending your webhook data. For this to work, your server must be correctly configured to support HTTPS with a valid server certificate. Currently, Falu supports TLS v1.1, 1.2, and 1.3.

CSRF protection

Most web frameworks today enforce CSRF tokens, which are a way of protecting applications and users from cross-site request forgery (CSRF) attacks. With these tokens, a server-side application validates that a POST request includes the expected token and rejects the request if the token is missing or invalid. CSRF tokens can prevent CSRF attacks by making it impossible for an attacker to construct a fully valid HTTP request suitable for feeding to a victim user.

However, this security measure might also prevent your site from processing legitimate events from Falu as we do not presently support it. For this reason, you might need to exempt the webhooks route from CSRF protection.

Verify webhook signatures

You should verify your webhook signatures to validate that, indeed, received events are sent from Falu.