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

# Webhooks

> Receive changes in the state of invoices, debtors, and debt collection cases in your own system.

With webhooks, it is possible to send changes in the state of an invoice to an external system. An example of this is when you want to set up a delivery stop for a customer in the accounts, when an invoice of the customer is offered for collection. Normally, you would have to log into Payt to see which invoices are presented for collection and which customer it concerns. By means of webhooks, it is possible to automatically send a message (in the form of an HTTP request) to an external URL when an invoice is presented for collection.

## Delivery

* Webhooks are delivered only to an HTTPS URL.
* They are sent as a POST request with a JSON body.
* All dates and timestamps are in [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time), formatted as [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
* Redirects are followed.
* Webhooks originate from a fixed IP address. See [IP addresses](/reference/ip-addresses).

Each delivery includes these headers:

| Header                             | Description                                                                                                   |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `X-PAYT-DELIVERY`                  | A UUID identifying the delivery attempt.                                                                      |
| `X-PAYT-ADMINISTRATION-IDENTIFIER` | The Payt internal identifier of the administration, when the event relates to an object of an administration. |
| `X-PAYT-SIGNATURE`                 | HMAC signature of the payload. See [Verification](/webhooks/verification).                                    |

### Payload

* Every webhook contains a `debtor` and an `administration` object, used to identify the corresponding debtor or administration.
* The context of an event is not always an invoice. It can also be a debtor, debt collection case, payment plan or planned payment. Connected invoices can be traced back through the invoice numbers in the nested data.
* For OAuth applications, payloads only include fields your application is allowed to read via the granted OAuth scopes. For example, without the `debtors:read` scope, debtor details are omitted from the payload.

## Retries and timeout

* The timeout for a webhook is 10 seconds. If your endpoint does not respond within 10 seconds, the attempt is considered failed.
* Delivery is attempted up to 10 times with an increasing interval between attempts. If no `200 OK` is returned after 10 attempts, the webhook is not sent again.
* If deliveries fail often within a certain time frame, the webhook is deactivated and an email is sent to you: to the notification email address of the administration, or to the developer email address of the application. Reactivate the webhook yourself once the processing problem is resolved.

## Reliability and ordering

* Delivery is asynchronous and **order is not guaranteed**. If two events occur simultaneously (for example, `invoice_paid` and `payment_plan_finished`), their order is unpredictable. You may even receive events for an invoice before its `invoice_created` event arrives.
* A useful pattern: when you receive an event for an object you don't know yet, respond with `404 Not Found`. The event is retried and can be processed after `invoice_created` arrives.
* Event timestamps are not guaranteed to be unique, even within the same invoice or debtor. Simultaneous events most likely share the same timestamp.

## Matching records

The `origin_id` of the administration contains, if known, the administration code of the external system loaded by Payt (for example Exact Online or Twinfield). This value can be empty, changed or outdated.

Record the Payt database ids (the `id` attribute) in your own system and link them to your own IDs, so incoming events can be matched to the correct debtors and invoices.

<Warning>
  **Matching on invoice number alone is insufficient.** Invoice numbers are unique per administration, but the same number can appear across multiple administrations. If you process webhooks from multiple Payt administrations, account for invoice numbers occurring in more than one administration.
</Warning>

## Mutual TLS

Mutual TLS (mTLS) is a security protocol that ensures both the client and the server in a communication channel authenticate each other using digital certificates. Unlike standard TLS, which only verifies the server’s identity, mTLS adds an additional layer of security by also verifying the client's identity.

This mutual authentication ensures that:

* The server trusts the client sending requests.
* The client trusts the server receiving the requests.

By implementing mTLS, you can protect sensitive data, prevent unauthorized access, and reduce the risk of man-in-the-middle attacks.

<Card title="Download the Payt mTLS public certificate" href="https://backend.paytsoftware.com/certificates/payt_mtls_certificate_2026.crt">
  `payt_mtls_certificate_2026.crt` (valid until 2027-01-03)
</Card>

You will be notified by email when a new certificate is available. We use the email address that is specified in the relevant webhook for this.