Webhooks
Request Finance API - Webhooks Documentation
Introduction
Webhooks in Request Finance allow you to receive real-time notifications about changes to invoices, such as when they are created, accepted, canceled, rejected, or paid. This guide explains how to set up and secure webhooks for your integration with the Request Finance API.
Prerequisites
Whitelist Your Account: Before you can use webhooks, you need to be whitelisted for the feature. Contact Request Finance support to request access.
Setting Up Webhooks
Step 1: Add Webhook URL and Secret
Once your account is whitelisted, follow these steps to add your webhook URL and secret:
Navigate to the
Settings > Developer > Apps
page in the Request Finance dashboard.Create or edit your OAuth application.
Enter your webhook URL.
Enter your webhook secret. This secret is used to verify the integrity of the incoming requests.
The webhook URL and secret are mandatory for events to be sent to your URL.
Step 2: Verify Webhook Setup
To ensure that your webhooks are working correctly, you can use testing services like Webhook.site or Webhook Test. These services allow you to inspect the incoming webhook requests and verify their format.
Webhook Events
When an event occurs, Request Finance will send a JSON payload to your webhook URL. The payload format is as follows:
Event Sources
Depending on the usage of your OAuth application, you will receive events for different types of invoices:
If your OAuth application is not yet used for interracting with the Request Finance API, you will still receive webhook events for every invoice sent or received by your account or organization.
If your OAuth application follows the Authorization Code Flow and is used to read users' data, you will receive webhook events for every invoice sent or received by users who have authorized your application.
If your OAuth application follows the Client Credentials Flow and sends invoices, you will receive webhook events for every invoice it creates.
Event Types
The event
field can have the following values:
create
: When an invoice is created.accept
: When an invoice is accepted (by the buyer).cancel
: When an invoice is canceled (by the seller).reject
: When an invoice is rejected (by the buyer).paid
: When an invoice is paid.
Securing Your Webhooks
To ensure that the webhook requests are legitimate and not coming from unauthorized sources, you should verify the X-Webhook-Signature
HTTP header sent with each event. This header contains the SHA256 signature of the request body, generated using your webhook secret.
Verification Example in Node.js
Here's an example of how to verify the webhook signature in Node.js:
Last updated