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

# Webhooks

> Learn how to use webhooks to receive real-time updates from connected accounting systems.

Webhooks allow you to receive real-time notifications about events happening in your connected accounting systems. This enables you to automate workflows and keep your data in sync without the need for constant polling.

## Unified Webhooks

Maesn supports a single, unified webhook type for all systems.

Endpoint url : `POST /webhooks`

Subscriptions are created **per customer**, so each customer events is received through the related subscription.

Requires both the `X-API-KEY` and the `X-ACCOUNT-KEY` in the header.

Systems that support customer-based webhooks:

* `businesscentral`
* `exact-nl`
* `freshbooks`
* `lexware-office`
* `moneybird`
* `qonto`
* `quickbooks`
* `weclapp`
* `xero`

## Setting up a webhook

To set up a webhook, you need to create a subscription by sending a POST request to the `/webhooks` endpoint.

The request body support the following parameters:

* `callbackUrl`: The URL where you want to receive webhook events.
* `eventType`: The type of event you want to subscribe to (e.g., `CREATED`, `UPDATED`, `DELETED`).
* `resource`: The resource you want to monitor (e.g., `INVOICE`, `CUSTOMER`).

In each target system page, you can check the required input parameters for the request body.

## Getting events

Once a webhook is set up, you will start receiving events at the specified callback URL. Each event will contain information about the resource that triggered the event, including its event type and ID.
The received event body will look similar to this:

```json Example event body theme={null}
{
    "eventType": "CREATED",
    "filterDate": "2023-10-01T00:00:00Z",
    "resource": "INVOICE",
    "resourceId": "bca91f06-0414-4b24-81fa-8489105afceb"
}
```

`Note`: for Business Central, Quickbooks and Xero the notification will be an array of objects.

## Handling events

When your server receives a webhook event, it should process the event according to your application's logic. This may involve updating records in your database, triggering other workflows, or sending notifications.

## Deleting a webhook

If you no longer need a webhook, you can delete it by sending a `DELETE` request to the `/webhooks/{webhookId}`endpoint.

## Webhook Authentication

All received events to the callback URL include an X-MAESN-SIGNATURE header containing an HMAC-SHA256 signature for verification.

### How to Verify

1. Get the signature from the `X-MAESN-SIGNATURE` header
2. Compute HMAC-SHA256 of the raw request body using the webhook secret returned during webhook creation
3. Compare the computed signature with the header value

```javascript Node.js theme={null}
const crypto = require('crypto');

const expectedSig = crypto
  .createHmac('sha256', Buffer.from(secret, 'hex'))
  .update(body)
  .digest('hex');

const isValid = expectedSig === headerSig;
```

<Warning>
  Always use the raw request body before parsing JSON. Your webhook secret is provided when creating the webhook endpoint.
</Warning>