Skip to main content
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:

​
Payload

  • Webhooks contain an administration object and, in most events, a debtor object, used to identify the corresponding administration or debtor. debtor is null when the event is not linked to a debtor, for example a message_created event for an incoming email that could not be matched to a debtor.
  • 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. A nested object your application may not read is sent as an empty object ({}) rather than being left out: without the debtors:read scope, for example, "debtor": {} is sent. An empty object therefore means “not readable with your scopes”, while null means the record has no such relation. If your application lacks the read scope for the event’s own object, no delivery is sent at all. Webhooks configured on an administration are not scope-limited and always receive the full 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)
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.
Last modified on September 28, 2026