Webhooks Overview

Another way to receive data is by setting up Webhook events in your backend. Webhooks can be used to notify your systems about events as they occur in a Railz connection. Using the Railz Dashboard™, you can setup several webhook endpoints to be notified of such events. You are able to set a maximum of 5 webhook event types per url.

Railz uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when a business's accounting data has been synchronized, a new connection was created, or the posting of a transaction was successful.

📘

Setting up Webhooks in your Sandbox

You can also test webhooks without setting up your own endpoint following the instructions in Testing Webhooks in Sandbox.

Best Practices

Order of Events

Railz does not guarantee the delivery of events in the order in which they are generated. For example, creating a connection might generate the following events:

  • New Connection
  • Authentication Completed
  • Data Synchronized (if connection successful)
  • Connection Disconnected

Your endpoint should not expect delivery of these events in this order and should handle this accordingly.

Return a 2xx Response

Your server must accept HTTP POST requests and respond to each event with a 2xx response, so we can have a confirmation that the transmission of the event was properly completed.

Built-in Retries

Railz webhooks have built-in retry methods for 3xx, 4xx, or 5xx response status codes. If Railz doesn’t receive a 2xx response status code within 60 seconds for an event, we will attempt sending a webhook event twice. After that we mark the event as failed and stop trying to send it to your endpoint.

Secure your Webhooks (recommended)

Your server must have a valid SSL certificate. Use webhook signatures or webhook authorization headers to verify that Railz generated a webhook request and that it didn’t come from a server acting like Railz.