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, formatted as ISO 8601.
- Redirects are followed.
- Webhooks originate from a fixed IP address. See 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. |
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.
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.
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.
Download the Payt mTLS public certificate
payt_mtls_certificate_2026.crt (valid until 2027-01-03)
