Webhooks
Attributes
Attribute | Type | Description | |
---|---|---|---|
id |
Integer |
Unique identifier in Fakturoid | |
webhook_url |
String |
URL of webhook endpoint | |
auth_header |
String |
Value send in Authorization header |
|
active |
Boolean |
Send webhook? | |
events |
Array[String] |
List of events when webhook is fired | |
url |
String |
Webhook API address | |
created_at |
DateTime |
Date and time of webhook creation | |
updated_at |
DateTime |
Date and time of last webhook update |
-
Required attribute (must always be present).
-
Read-only attribute (cannot be changed).
-
Write-only attribute (will not be returned).
-
Unmarked attributes are optional and can be omitted during request.
Restrictions
- New webhooks are available only for accounts with plans Základ and Komplet.
- Only integrations using the authorization code flow are allowed to manage webhooks. 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.
Event name | Additional payload | Description |
---|---|---|
invoice_created |
Invoice was created. Event is triggered automatically, including when invoice is created by recurring generator or as a result of paying proforma. | |
invoice_updated |
Invoice was updated. Event is also triggered when tags are modified or attachment is removed. | |
invoice_removed |
Invoice was deleted and moved to the trash. | |
invoice_restored |
Invoice was restored from the trash. | |
invoice_overdue |
Invoice was marked as overdue. | |
invoice_paid |
payment: Payment |
Payment was added to document and marked it as paid. Payload contains payment data. |
invoice_payment_added |
payment: Payment |
Payment was added to the invoice, but didn't mark it as paid. Payload contains payment data. |
invoice_payment_removed |
payments: Array[Payment] |
Invoice was marked as unpaid, and the payments in the additional payload were removed. |
invoice_sent |
Email with the invoice was sent to the subject. | |
invoice_locked |
Invoice was locked. | |
invoice_unlocked |
Invoice was unlocked | |
invoice_cancelled |
Invoice was marked as cancelled. | |
invoice_cancellation_removed |
Cancellation was removed. | |
invoice_uncollectible |
Invoice was marked as uncollectible. | |
invoice_uncollectible_removed |
Uncollectibility was removed. |
Event name | Additional payload | Description |
---|---|---|
generator_created |
Generator was created. | |
generator_updated |
Generator was updated. Event is also triggered when tags are modified or attachment is removed. | |
generator_removed |
Generator was deleted and moved to the trash. | |
generator_restored |
Generator was restored from the trash. |
Event name | Additional payload | Description |
---|---|---|
recurring_generator_created |
Recurring generator was created. Event is also triggered when tags are modified, attachment is removed or recurring generator is activated again. | |
recurring_generator_updated |
Recurring generator was updated. | |
recurring_generator_removed |
Recurring generator was deleted and moved to the trash. | |
recurring_generator_restored |
Recurring generator was restored from the trash. | |
recurring_generator_invoice_created |
invoice: Invoice |
Recurring generator created an invoice. |
recurring_generator_paused |
Recurring generator was paused. |
Event name | Additional payload | Description |
---|---|---|
expense_created |
Expense was created. | |
expense_updated |
Expense was updated. Event is also triggered when tags are modified or attachment is removed. | |
expense_removed |
Expense was deleted and moved to the trash. | |
expense_restored |
Expense was restored from the trash. | |
expense_overdue |
Expense was marked as overdue. | |
expense_paid |
payment: Payment |
Expense was marked as paid. Payment object is included in payload. |
expense_payment_added |
payment: Payment |
Payment was added to the expense, but the document is still not marked as paid. |
expense_payment_removed |
payments: Array[Payment] |
Expense was marked as unpaid, and payments in additional payload were removed. |
expense_locked |
Expense was locked. | |
expense_unlocked |
Expense was unlocked |
Event name | Additional payload | Description |
---|---|---|
inbox_file_created |
Inbox file was created. | |
inbox_file_updated |
Inbox file was updated. | |
inbox_file_removed |
expense: Expense |
Inbox file was deleted. If expense was created from inbox file, expense attribute is contained in payload. |
inventory_item_removed_all |
count: Integer |
All inbox files were deleted. Payload contains only number of deleted records. |
inbox_file_ocr_processing_failed |
Uploading file for OCR processing failed. | |
inbox_file_ocr_processing_rejected |
OCR processing was rejected by external service. | |
inbox_file_ocr_processed |
OCR data were extracted. |
Event name | Additional payload | Description |
---|---|---|
inventory_item_created |
Inventory item was created. | |
inventory_item_updated |
Inventory item was updated. | |
inventory_item_removed |
Inventory item was deleted. | |
inventory_item_archived |
Inventory item was archived. | |
inventory_item_unarchived |
Inventory item was unarchived. |
Event name | Additional payload | Description |
---|---|---|
inventory_move_created |
inventory_item: InventoryItem |
Inventory move was created. Modified InventoryItem is included in payload. |
inventory_move_updated |
inventory_item: InventoryItem |
Inventory move was updated. Modified InventoryItem is included in payload. |
inventory_move_removed |
inventory_item: InventoryItem |
Inventory move was deleted. Modified InventoryItem is included in payload. |
Event name | Additional payload | Description |
---|---|---|
subject_created |
Subject was created. | |
subject_updated |
Subject was updated. | |
subject_removed |
Subject was deleted. |
Webhook index
Request
GET
https://app.fakturoid.cz/api/v3/accounts/{slug}/webhooks.json
Headers
Name | Value |
---|---|
User-Agent |
YourApp (yourname@example.com) |
URL Parameters
Name | Description | Type | Example |
---|---|---|---|
slug |
Account name | String |
applecorp |
Query Parameters
Name | Description | Type | Example |
---|---|---|---|
page |
Page number (40 records per page) | Integer |
2 |
Response
Status
200 OK
Body
[
{
"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
Request
GET
https://app.fakturoid.cz/api/v3/accounts/{slug}/webhooks/{id}.json
Headers
Name | Value |
---|---|
User-Agent |
YourApp (yourname@example.com) |
URL Parameters
Name | Description | Type | Example |
---|---|---|---|
slug |
Account name | String |
applecorp |
Response
Status
200 OK
Body
{
"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, thelocation
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.
Request
POST
https://app.fakturoid.cz/api/v3/accounts/{slug}/webhooks.json
Headers
Name | Value |
---|---|
User-Agent |
YourApp (yourname@example.com) |
Content-Type |
application/json |
URL Parameters
Name | Description | Type | Example |
---|---|---|---|
slug |
Account name | String |
applecorp |
Body
{
"webhook_url": "https://example.com/webhook",
"auth_header": "Bearer TOKEN",
"events": [
"invoice_created",
"invoice_updated",
"invoice_paid"
]
}
Response
Status
201 Created
Headers
Name | Value |
---|---|
Location |
https://app.fakturoid.cz/api/v3/accounts/applecorp/webhooks/5.json |
Body
{
"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"
}
Request with invalid data
Body
{
"webhook_url": "https://example.com/webhook",
"events": []
}
Response
Status
422 Unprocessable Entity
Body
{
"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.
Request
PATCH
https://app.fakturoid.cz/api/v3/accounts/{slug}/webhooks/{id}.json
Headers
Name | Value |
---|---|
User-Agent |
YourApp (yourname@example.com) |
Content-Type |
application/json |
URL Parameters
Name | Description | Type | Example |
---|---|---|---|
slug |
Account name | String |
applecorp |
id |
Webhook ID | Integer |
17 |
Body
{
"active": false
}
Response
Status
200 OK
Body
{
"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"
}
Request with invalid data
Body
{
"events": []
}
Response
Status
422 Unprocessable Entity
Body
{
"errors": {
"events": [
"can't be empty",
]
}
}
Delete Webhook
After deleting the webhook the server will respond with 204 No Content
.
Request
DELETE
https://app.fakturoid.cz/api/v3/accounts/{slug}/webhooks/{id}.json
Headers
Name | Value |
---|---|
User-Agent |
YourApp (yourname@example.com) |
URL Parameters
Name | Description | Type | Example |
---|---|---|---|
slug |
Account name | String |
applecorp |
id |
Webhook ID | Integer |
1 |
Response
Status
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
Attribute | Type | Description |
---|---|---|
webhook_id |
Integer |
Unique identifier of the webhook |
event_name |
String |
Name of the event |
created_at |
DateTime |
Date and time of the event |
body |
Object |
Event payload |
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
}
}