Webhooks

Attributes

Restrictions

• Webhooks are only available in paid plans.
• Every account can create webhooks in their account in Fakturoid UI. How to create webhooks in your account see the support page (cz).
• In addition to the UI, new webhooks can also be created and managed via API using both the authorization code flow and the client credentials flow:
• Authorization code flow
  • To manage webhooks via API, please contact our support team first. Without prior authorization, a Status 403 response will be returned
• Client credentials flow
  • Webhook management must be enabled in the UI in your user screen Settings → User account.
• Both OAuth integrations and client credentails can manage only their own webhooks; access to other webhooks within the account is restricted.
• When an OAuth integration or client credentials are 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 Content 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 Content 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
  }
}

You can use one of the following services to test webhooks:

• https://beeceptor.com/
• https://www.postb.in/
• https://www.svix.com/play/