---
title: "Webhooks"
slug: "webhooks"
updated: 2025-11-13T14:59:38Z
published: 2025-11-13T14:59:38Z
canonical: "help.frisbii.com/webhooks"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.frisbii.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

A webhook in web development is a method of augmenting or altering the behavior of a web page or web application with custom callbacks. These callbacks may be maintained, modified, and managed by third-party users and developers who may not necessarily be affiliated with the originating website or application.

> [!WARNING]
> Need more details?
> 
> Find more technical information about our webhooks and what they contain in our [technical documentation](https://docs.frisbii.com/reference/intro_webhooks).

## Access the Webhooks Interface

In the navigation on the left hand side, click on **Configurations > Integrations and tools > Webhooks**.

## Webhook Configuration

1. Click on **Configuration** in the top right corner.
2. In the **Webhook urls** add a URL and click on **Add**.
3. Select one or more [Event types](https://docs.frisbii.com/reference/getevents), you have the choice between
  - Invoice events
  - Subscription events
  - Customer events
4. Add an email address to the **Alert emails** box and click on **Add**.
5. Enter a **Username** and a **Password** in the **Credentials** box.
6. You can copy the **Secret** key by clicking on ![Reepay_Admin_-_Copy_Icon.png](https://cdn.document360.io/b84e1b5d-2ba6-4465-8c62-fb45a2f31314/Images/Documentation/167e6a9cab327a(2).png).
7. Activate the webhook using the **Status** switch.
8. Click on **Save**.

## Explanation for pending Webhooks

Sometimes webhooks stay on pending and it seems they are not even sent to your server.

### First in, first out

All webhooks are sent in **FIFO (first in, first out) order grouped for each customer**.

That means that you can expect to get events for each customer in the right order.

Example: You do not get CUSTOMER_UPDATED before CUSTOMER_CREATED.

> [!NOTE]
> Note
> 
> If your service **does not return an HTTP code between 200 and 299**:
> 
> - we consider the webhook as failed
> - we will block the next webhooks for that specific customer

### Considerations for webhooks

- Your endpoint must respond within **30 seconds**.
- A response with **HTTP code 2XX** is considered successful. All other responses are considered as **failures**.
- The content of a webhook notifies of an event in the Frisbii Payment system, the affected resources, and the event type, but **does not in itself carry any state**. It is recommended to subsequently use the API to get the updated state of a resource.
- Your **endpoint must be idempotent**, allowing multiple invocations of the same webhook with the same result as one invocation.

This is due to the fact that communication errors can result in a scenario where Frisbii Payments considers an invocation as failed even though it has been received. We will retry failed invocations. See below.
- In failure scenarios, webhooks can be delivered out of order. Therefore **always use the API to get the actual state of a resource**.

An example is a subscription cancellation followed by an uncancel. The cancel webhook could be received after the uncancel.

### Best practice

Frisbii Payment will send max. 10 webhook requests to your server at a time.

A good practice is to offload events to a local queue on your side and return **200 OK on each**.

That means you will respond quickly and have no events blocking each other. You can then process each event from your queue and update your assets without any problems.

---

## Examples of webhooks and contents

`INVOICE_CREATED`

```json
{
"id":"cd614e4887c8c12ae67fbf80c3ffc1b6",
"timestamp":"2025-11-11T13:19:18.99Z",
"signature":"7718c7690b51f2c9b1cee2a173b6eb81aab2b4849e8eb8544c3a3ee2640231e1",
"invoice":"inv-52",
"subscription":"sub-0022",
"customer":"cust-0005",
"event_type":"invoice_created",
"event_id":"f131c9306108777bab8e1e0278e76480"
}
```

`INVOICE_REFUND`

```json
{
"id":"b6cfe85ab18d65d2750f093a6e59400c",
"timestamp":"2025-11-11T13:33:04.803Z",
"signature":"9674d2ff0482157d149ade9d071243df448f891e36c42dcb2fba6eaa887b7401",
"invoice":"inv-52",
"subscription":"sub-0022",
"customer":"cust-0005",
"transaction":"5ccb1455b072adf948c0e93d4a26e103",
"event_type":"invoice_refund",
"event_id":"e1d018b2fb86f62464ea219f81636598",
"credit_note":"5ccb1455b072adf948c0e93d4a26e103"
}
```

`SUBSCRIPTION_RENEWAL`

```json
{
"id":"abefe07e4a742cce106695dd8238bdcb",
"timestamp":"2025-11-11T13:19:18.99Z",
"signature":"12b4423aaf65ce0978fb0ba752d147618051fc1a9ac0f9c50377a456922848e7",
"invoice":"inv-52",
"subscription":"sub-0022",
"customer":"cust-0005",
"event_type":"subscription_renewal",
"event_id":"20127731fe4a68ef674c4d4cffcda2af"
}
```

`SUBSCRIPTION_EXPIRED`

```json
{
"id":"2585ec2c89395a515c8f47afa2920899",
"timestamp":"2025-11-11T13:33:04.738Z",
"signature":"99fcf1acddd18bad4615fd95a52934a28bc589cb5682efbe28a34fb7baf460fd",
"subscription":"sub-0022",
"customer":"cust-0005",
"event_type":"subscription_expired",
"event_id":"8ae7b7b17a5b1612ea38e9f714c9259f"
}
```

`CUSTOMER_PAYMENT_METHOD_ADDED`

```json
{
"id":"e1c69ad60688cfb4cf38ca6a6c75959a",
"timestamp":"2025-11-11T13:28:14.601Z",
"signature":"3106e26798b59a20b3b0f8135ec6fe4205c7b5e8fb62498b6d19bea82317e64c",
"customer":"cust-0005",
"event_type":"customer_payment_method_added",
"event_id":"3e17853629d60230e1178e436087b699",
"payment_method":"ca_dc1a6deb3b702b6564531ec21d1da6cf",
"payment_method_reference":"cs_4c5ad0ac03ddd97efa33d7b48ef18b9a"
}
```