> For the complete documentation index, see [llms.txt](https://docs.payrexx.com/developer/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payrexx.com/developer/guides/webhook.md).

# Webhook

Webhooks can be configured in the settings of your Payrexx merchant account. Find this in the navigation under "Webhooks".

{% hint style="info" %}
Webhooks are fired whenever the status of a transaction or subscription changes.
{% endhint %}

## Configuration

* Submit an accessible URL / IP address where you receive and process the data
* Decide whether webhooks should be retried in case of an error at the processing server
* Choose between two content types
  * Normal (PHP-Post): application/x-www-form-urlencoded
  * JSON: application/json and is best used for all different applications

### Retry on failure

When activated, the Payrexx software tries to send the webhook 10 times until a successful response is received.

These attempts will be fired at the following intervals:

1. ASAP (max. 1 - 1.5 minutes after the first synchronous attempt)
2. 15 minutes after the last attempt
3. 1 hour after the last attempt
4. 2 hours after the last attempt
5. 4 hours after the last attempt
6. 24 hours after the last attempt
7. 24 hours after the last attempt
8. 24 hours after the last attempt
9. 24 hours after the last attempt
10. 24 hours after the last attempt

### Timeout

The server needs to send a response within 20 seconds. Otherwise, the request times out. The log shows HTTP status 0, and response body "Operation timed out after 20000 milliseconds with 0 bytes received".

## How to use

For an integration into a webshop, you will create a [Payrexx Gateway](/developer/guides/gateway.md). After the transaction has been performed, you will get a notification request to your server. You can identify the transaction by `paymentLinkId` or `referenceId` in the [Invoice object](/developer/general-info/objects/invoice.md).

## Signature

To ensure security, verify each webhook by validating its signature. The signature is provided in the `X-Webhook-Signature` HTTP header and is generated as a lowercase hex-encoded SHA-256 HMAC using the raw request body and your signing key (treated as a UTF-8 string).

#### Important implementation details

* **Signed data:** Use the raw, unmodified request body. Do not re-serialize the parsed JSON.
* **Key encoding:** The signing key is used as a plain UTF-8 string, not Base64-decoded.
* **Signature encoding:** The resulting HMAC is hex-encoded (lowercase), not Base64.

## Data

The data will be either sent in [JSON format](https://en.wikipedia.org/wiki/JSON) or as [HTTP POST form-data](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST). In this documentation, the JSON format is used.

If not stated, all amounts are given in the currency's smallest unit. Example: `200` represents `CHF 2.00`.

## Examples

Currently, we only have an example written in PHP.

Download full PHP example with a corresponding MySQL database: [click here to download](https://showcase.payrexx.com/developers/examples/webhooks.zip).