Skip to main content
WEBHOOK

Authorizations

​
X-Qonto-Signature
string
header
required

The signature header follows the format t={timestamp},v1={signature}.

Verification steps:

  1. Extract the timestamp and signature from the signature header
  2. Reject the request if the timestamp is older than 5 minutes
  3. Recreate the signed payload: '{timestamp}.{raw_request_body}'
  4. Compute HMAC-SHA256 of the signed payload using your webhook secret as the key
  5. Compare the computed signature with the one in the header

Body

application/json
​
id
string<uuid>
required
Example:

"4d5418bb-bd0d-4df4-865c-c07afab8bb48"

​
number
string
required
Example:

"INV001"

​
purchase_order
string
required

Purchase order data added by the invoice’s initiator.

​
status
enum<string>
required
Available options:
draft,
unpaid,
paid,
canceled
Example:

"paid"

​
contact_email
string<email>
required

E-mail address of the invoice’s initiator.

Example:

"contact@qonto.com"

​
terms_and_conditions
string
required

The T&C data added by the invoice’s initiator.

Example:

"This is an example."

​
discount_conditions
string | null
required

Any discount for advance payment of the invoice. It is optional and is only for French organizations.

Example:

"Pas d’escompte accordé pour paiement anticipé."

​
late_payment_penalties
string | null
required

Late payment penalties applied in case of non-payment invoice. It is optional and is only for French organizations.

Example:

"En cas de non-paiement à la date d'échéance, des pénalités calculées à trois fois le taux d’intérêt légal seront appliquées."

​
legal_fixed_compensation
string | null
required

The legal fixed compensation applied in case late payment of the invoice. It is optional and is only for French organizations.

Example:

"Tout retard de paiement entraînera une indemnité forfaitaire pour frais de recouvrement de 40€."

​
header
string
required

The header text added by the credit note’s initiator.

Example:

"This is an example."

​
footer
string
required

The footer text added by the credit note’s initiator.

Example:

"This is an example."

​
currency
string
required
Example:

"EUR"

​
total_amount
object
required

Total amount that needs to be paid by the client.

​
vat_amount
object
required

VAT amount that is applicable to the invoice.

​
issue_date
string<date>
required

Date the initiator mentioned that the invoice was created.

Example:

"2022-03-01"

​
due_date
string<date>
required

Payment’s deadline added by the initiator.

Example:

"2022-03-01"

​
performance_date
string<date>
required
deprecated

DEPRECATED: This field is deprecated. Please use performance_start_date and performance_end_date instead.

The performance date represents when the job or service was completed by the client. Date the initiator mentioned that the contents of the invoice were performed.

Example:

"2022-03-01"

​
performance_start_date
string<date>
required

Start date of the performance period mentioned by the initiator for the invoice contents.

The performance period defines the date range during which the job or service was completed by the client. This field marks the beginning of that period and can be used together with performance_end_date to create a flexible date range instead of a single fixed date.

Example:

"2022-03-01"

​
performance_end_date
string<date>
required

End date of the performance period mentioned by the initiator for the invoice contents.

This field defines the end of the performance date range, allowing the work or service to have been completed anytime between performance_start_date and performance_end_date. When used together with performance_start_date, it creates a flexible time window rather than specifying completion on a single specific date.

Example:

"2022-03-31"

​
created_at
string<date-time>
required

Date the invoice was created. Note that this is a machine date.

Example:

"2022-03-04T17:58:30+02:00"

​
finalized_at
string<date-time>
required

Date the invoice was transitioned from Draft to Unpaid status.

Example:

"2022-03-04T17:58:30+02:00"

​
paid_at
string<date-time>
required

Date on which the invoice was paid.

Example:

"2022-03-04T17:58:30+02:00"

​
stamp_duty_amount
string
required
Required string length: 4 - 15
Example:

"1.00"

​
items
object[]
required
​
client
object
required

Client that needs to pay the invoice.

​
payment_methods
object[]
required
​
organization
object
required

Information of the organization at the time the document was issued.

​
invoice_type
enum<string>
required

Nature of the invoice.

  • standard: the invoice covers the whole amount of the items it lists.
  • deposit: the invoice covers an advance payment on a larger order.
  • partial: progress invoice (facture de situation). The invoice covers a share of the work described by its items, so total_amount is a fraction of the value of those items.
  • balance: the invoice covers the remainder of an order, net of a deposit.

Only standard invoices are guaranteed to have total_amount equal to the sum of their line items. For every other type, rely on total_amount and total_amount_cents for the amount actually invoiced and due. The progress share of a partial invoice is not exposed by the API.

Available options:
standard,
deposit,
partial,
balance
Example:

"standard"

​
attachment_id
string<uuid>

Attachment UUID corresponding to that particular invoice.
The attachment is generated asynchronously. While it is being generated this property is omitted from the response rather than returned as null, so treat an absent attachment_id as "not ready yet" and keep polling. After creating the invoice (by calling the POST /v2/client_invoices endpoint) or finalizing it, wait ~10s and then call the GET /v2/client_invoices/{id} endpoint until attachment_id is present.
This property enables you to get the invoice file by using the GET /v2/attachments/{id} endpoint.
The file is a PDF for invoices created on Qonto. Imported invoices keep their original file, which may also be a JPEG or a PNG, so read file_content_type from the attachment response instead of assuming application/pdf.

Example:

"4d5418bb-bd0d-4df4-865c-c07afab8bb48"

​
discount
object

Global discount that was applied to the invoice.

​
einvoicing_status
enum<string>

Only applicable to Italian organizations. Remains blank for French organizations.

Available options:
pending,
submitted,
declined,
approved,
not_delivered,
submission_failed
​
welfare_fund
object
​
withholding_tax
object
  • Only applicable for Italian organizations and Spanish freelancers.
  • Object which relates to an amount of tax paid by the client, rather than the supplier, for specific cases.
  • This amount is a percentage deducted from the total amount of the invoice after VAT application.
  • The rate field specifies the percentage of tax and amount field specifies the total amount of the tax.

Response

200

Webhook received successfully