Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improved webhook documentation: Formatting and added more context to the existing information #8

Open
wants to merge 1 commit into
base: gitbook
Choose a base branch
from
Open

Improved webhook documentation: Formatting and added more context to the existing information #8

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 15 additions & 9 deletions docs/webhooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Webhooks in Request Finance allow you to receive real-time notifications about c

## Prerequisites

1. **Create an OAuth app:** See [#authentication](going-live.md#authentication "mention")
1. **Create an OAuth app:** OAuth (Open Authorization) is an open standard for access delegation, commonly used to grant websites or applications limited access to user information without exposing credentials. To create an OAuth app, navigate to [#authentication](going-live.md#authentication "mention")
2. **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
Expand All @@ -21,16 +21,20 @@ Once your account is whitelisted, follow these steps to add your webhook URL and

1. Navigate to the `Settings > Developer > Apps` page in the Request Finance dashboard.
2. Create or edit your OAuth application.
3. Enter your webhook URL.
4. Enter your webhook secret. This secret is used to verify the integrity of the incoming requests.
3. Enter your webhook URL and a secret key. The secret is used to verify the integrity of incoming requests.

The webhook URL and secret are mandatory for events to be sent to your URL.

<figure><img src=".gitbook/assets/image (4).png" alt=""><figcaption><p>Edit your OAuth app, and add the webhook URL and secret</p></figcaption></figure>

### Step 2: Verify Webhook Setup

To ensure that your webhooks are working correctly, you can use testing services like [Webhook.site](https://webhook.site) or [Webhook Test](https://webhook-test.com/). These services allow you to inspect the incoming webhook requests and verify their format.
To ensure that your webhooks are working correctly, you can use testing services like [Webhook.site](https://webhook.site) or [Beeceptor](https://beeceptor.com/webhook-integration/). These tools act as intermediaries, capturing and displaying incoming requests so you can:

- **Verify Payload Format**: Inspect headers, body (JSON/XML), and query parameters to ensure data aligns with your expectations.
- **Test Error Handling**: Simulate delayed responses, timeouts, or error status codes (e.g., 4xx/5xx) to see how your system recovers.
- **Debug in Real Time**: Monitor live traffic without deploying code to production.


## Webhook Events

Expand Down Expand Up @@ -61,11 +65,13 @@ Depending on the usage of your OAuth application, you will receive events for di

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.
| Event Type | Description |
|------------|----------------------------------------------|
| 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

Expand Down