> For the complete documentation index, see [llms.txt](https://docs.payengine.co/developer-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payengine.co/developer-docs/webhooks/build-a-webhook-endpoint.md).

# Build a webhook endpoint

Write the code that properly handles webhook notifications.

The first step to adding webhooks to your integration is to build your own custom endpoint. Creating a webhook endpoint on your server is no different from creating any page on your website.

For each event occurrence, we POST the webhook data to your endpoint in JSON format. The full event details are included and can be used after parsing the JSON into an event object. Thus, at minimum, that webhook endpoint needs to expect data through a POST request and confirm successful receipt of that data.

### Return 2xx status code quickly

To acknowledge receipt of an event, your endpoint must return a `2xx` HTTP status code. All response codes outside this range, including a `3xx` code, indicate to us that you did not receive the event.

If we don't receive a `2xx` HTTP status code, the notification attempt is repeated. After several failures to send, we mark the event as failed and stop trying to send it to your endpoint. After several days without receiving any `2xx` HTTP status code responses, we automatically disable your endpoint soon after it unaddressed.

{% hint style="danger" %}
If the endpoint does not return within **3 seconds**, it is recorded as a failed delivery attempt.
{% endhint %}

Because properly acknowledging receipt of the webhook notification is important, your endpoint should return a `2xx` HTTP status code prior to any complex logic that could cause a timeout.

### Test that your endpoint works

As your webhook endpoint is used asynchronously, its failures may not be obvious to you until it's too late. For example, after it's been disabled. Always test that your endpoint works.

{% tabs %}
{% tab title="NodeJS" %}

```javascript
app.post("/webhook", (req, res) => {
    const header = req.header("x-pf-signature");
    const body = req.body;
    const secret = process.env.PF_WEBHOOK_SECRET
    
    const details = header.split(",").reduce(
        (obj, item) => {
            const kv = item.split("=");
            if (kv[0] === "t") {
                obj.timestamp = kv[1];
            }
            if (kv[0] === "s") {
                obj.signature = kv[1];
            }
            return obj;
        }, { timestamp: -1, signature: "" }
    );
    if (!details || details.timestamp === -1) {
        throw new Error('Unable to extract timestamp and signature from header')
    }
    
    const payload = `${details.timestamp}.${JSON.stringify(body)}`
    const expectedSignature = crypto
        .createHmac('sha256', secret)
        .update(payload, 'utf-8')
        .digest('hex')
    
    if (details.signature !== expectedSignature) {
        throw new Exception('Signature mismatch')
    }
});
```

{% endtab %}

{% tab title="Sample Payload (JSON)" %}

```javascript
{
  event_uid: <unique_event_id>,
  event: 'MERCHANT_CREATED',
  data: {
    id: <merchant_id>, 
    account_id: <account_id>,
    boarding_gid: <onboarding_id>
  }
}

```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.payengine.co/developer-docs/webhooks/build-a-webhook-endpoint.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
