Webhooks

Attributes

Restrictions

• New webhooks are available only for accounts with plans Základ and Komplet.
• Every account can create webhooks in their account in Fakturoid UI. How to create webhooks in you account see the support page (cz).
• In addition to UI, new webhooks can also be created and managed via API. This option is currently restricted only to integrations using the authorization code flow that were approved by us. Otherwise, a Status 403 response will be returned.
• To manage webhooks via the API, please contact our support team first. Without prior authorization, a Status 403 response will be returned.
• OAuth integration can manage only its own webhooks; access to other webhooks within the account is restricted.
• When an OAuth integration is revoked, all associated webhooks are automatically deleted.

Events

Webhooks are triggered when one of resources listed below is modified. Action may be triggered by user interaction, API call, or automatically (e.g. invoice is marked as overdue). Some events may include additional payload, which contains related resources to the event. For more information about the payload, please refer to the section on Payload Content.

Webhook index

[
  {
    "id": 5,
    "webhook_url": "https://example.com/webhook",
    "auth_header": "Bearer TOKEN",
    "active": true,
    "events": [
      "invoice_created",
      "invoice_updated",
      "invoice_paid"
    ],
    "url": "https://app.fakturoid.cz/api/v3/accounts/applecorp/webhooks/5.json",
    "created_at": "2024-06-12T13:29:23.568+02:00",
    "updated_at": "2024-06-12T13:29:23.568+02:00"
  },
  …
]

Webhook Detail

{
  "id": 5,
  "webhook_url": "https://example.com/webhook",
  "auth_header": "Bearer TOKEN",
  "active": true,
  "events": [
    "invoice_created",
    "invoice_updated",
    "invoice_paid"
  ],
  "url": "https://app.fakturoid.cz/api/v3/accounts/applecorp/webhooks/5.json",
  "created_at": "2024-06-12T13:29:23.568+02:00",
  "updated_at": "2024-06-12T13:29:23.568+02:00"
}

Create Webhook

• After successful template creation, you will receive a 201 Created response from the server, the location header will be set to the address of the newly created template.
• If non-valid data is sent, you will receive a 422 Unprocessable Entity response from the server and a JSON with a list of errors in the sent data.

{
  "webhook_url": "https://example.com/webhook",
  "auth_header": "Bearer TOKEN",
  "events": [
    "invoice_created",
    "invoice_updated",
    "invoice_paid"
  ]
}

{
  "id": 5,
  "webhook_url": "https://example.com/webhook",
  "auth_header": "Bearer TOKEN",
  "active": true,
  "events": [
    "invoice_created",
    "invoice_updated",
    "invoice_paid"
  ],
  "url": "https://app.fakturoid.cz/api/v3/accounts/applecorp/webhooks/5.json",
  "created_at": "2024-06-12T13:29:23.568+02:00",
  "updated_at": "2024-06-12T13:29:23.568+02:00"
}

{
  "webhook_url": "https://example.com/webhook",
  "events": []
}

{
  "errors": {
    "events": [
      "can't be empty",
    ]
  }
}

Update Webhook

• If webhook is successfuly updated the server will respond with 200 OK and a JSON body with its data.
• Request with invalid data will result in response 422 Unprocessable Entity with a JSON body describing errors found in the request.

{
  "active": false
}

{
  "id": 5,
  "webhook_url": "https://example.com/webhook",
  "auth_header": "Bearer TOKEN",
  "active": false,
  "events": [
    "invoice_created",
    "invoice_updated",
    "invoice_paid"
  ],
  "url": "https://app.fakturoid.cz/api/v3/accounts/applecorp/webhooks/5.json",
  "created_at": "2024-06-12T13:29:23.568+02:00",
  "updated_at": "2024-06-12T13:32:14.863+02:00"
}

{
  "events": []
}

{
  "errors": {
    "events": [
      "can't be empty",
    ]
  }
}

Delete Webhook

After deleting the webhook the server will respond with 204 No Content.

Webhook delivery

Webhooks are delivered as HTTP POST requests containing JSON payload to the URL specified in the webhook configuration. Optionally, Authorization header is set to the value specified in the auth_header attribute of the webhook.

Receiver must acknowledge the delivery by responding with a status code 2xx within 30 seconds. Otherwise the webhook delivery will be retried up to 5 times with an exponential backoff.

Payload Content

The body contains a resources related to event. For instance, when an invoice is created, the body contains an invoice key with the serialized Invoice object. When additional attributes are listed in the table, they are also included in the body object. More information may be found in the attributes section of API documentation related to the resource.

For example, when an invoice is paid, a payment object is included in the body object. Thus JSON contains an invoice object and a payment object under the body key.

{
  "webhook_id":5,
  "event_name":"invoice_paid",
  "created_at":"2024-06-13T14:06:20.924+02:00",
  "body":{
    "invoice":{
      "id":93,
      "custom_id":null,
      "document_type":"invoice",
      ...,
      "lines":[
        {
          "id":209,
          "name":"Magic mouse",
          "quantity":"5.0",
          "unit_name":"myš",
          "unit_price":"2000.0",
          "vat_rate":21,
          "unit_price_without_vat":"2000.0",
          "unit_price_with_vat":"2420.0",
          "total_price_without_vat":"10000.0",
          "total_vat":"2100.0",
          "native_total_price_without_vat":"10000.0",
          "native_total_vat":"2100.0",
          "inventory":null
        }
      ],
      "vat_rates_summary":[
        {
          "vat_rate":21,
          "base":"10000.0",
          "vat":"2100.0",
          "currency":"CZK",
          "native_base":"10000.0",
          "native_vat":"2100.0",
          "native_currency":"CZK"
        }
      ],
      "paid_advances":[

      ],
      "payments":[
        {
          "id":785,
          "paid_on":"2024-06-13",
          "currency":"CZK",
          "amount":"12100.0",
          "native_amount":"12100.0",
          "variable_symbol":"20240056",
          "bank_account_id":21,
          "tax_document_id":null,
          "created_at":"2024-06-13T14:06:20.743+02:00",
          "updated_at":"2024-06-13T14:06:20.769+02:00"
        }
      ],
      "attachments":[

      ],
      "html_url":"https://app.fakturoid.cz/applecorp/invoices/93",
      "public_html_url":"https://app.fakturoid.cz/applecorp/p/nENr3UCI6g/2024-0056",
      "url":"https://app.fakturoid.cz/api/v3/accounts/applecorp/invoices/93.json",
      "pdf_url":"https://app.fakturoid.cz/api/v3/accounts/applecorp/invoices/93/download.pdf",
      "subject_url":"https://app.fakturoid.cz/api/v3/accounts/applecorp/subjects/37.json",
      "created_at":"2024-06-13T10:33:33.031+02:00",
      "updated_at":"2024-06-13T14:06:20.800+02:00"
    },
    "payment":{
      "id":785,
      "paid_on":"2024-06-13",
      "currency":"CZK",
      "amount":"12100.0",
      "native_amount":"12100.0",
      "variable_symbol":"20240056",
      "bank_account_id":21,
      "tax_document_id":null,
      "created_at":"2024-06-13T14:06:20.743+02:00",
      "updated_at":"2024-06-13T14:06:20.743+02:00"
    }
  }
}

When payload relates to bulk action, additional attributes are included under pluralized resource name. For example, when all inbox files are removed, the payload contains an inbox_files key with number of removed records.

{
  "webhook_id": 13,
  "event_name": "inbox_file_removed_all",
  "created_at": "2024-06-13T14:16:33.114+02:00",
  "body": {
  "inbox_files": {
    "count": 2
  }
}