Webhook Events

faktoora sends HTTP POST requests to your registered endpoint whenever various document events occur. Below is the official event specification, detailing each event name (action or status) and its trigger.

Event	Trigger
invoiceCreate	Outgoing invoice created (backend-worker event)
invoiceOverdue	Cron job marks invoice as overdue
invoiceSent	Invoice sent via email
invoiceIncomingCreate	Incoming invoice first created or validated (email/API)
invoiceIncomingSent	Incoming invoice forwarded via email
offerCreate	Quotation (offer) created (backend-worker event)
offerSent	Quotation sent via email
letterCreate	Letter document created (backend-worker event)
letterSent	Letter sent via email
reminderCreate	Reminder (dunning notice) created (backend-worker event)
reminderSent	Reminder sent via email
orderConfirmationCreate	Order confirmation created (backend-worker event)
orderConfirmationSent	Order confirmation sent
customerCreate	Customer created
productCreate	Product created

---

Managing Webhooks

Register, update, and delete webhook subscriptions via the /webhooks management API.

All webhook management endpoints require apiKeyAuth.

Endpoint	Method	Description
GET /webhooks	GET	List all registered webhook subscriptions.
POST /webhooks	POST	Register a new webhook subscription.
PATCH /webhooks/{id}	PATCH	Update an existing webhook subscription. {id} is a UUID.
DELETE /webhooks/{id}	DELETE	Remove a webhook subscription. Returns { "succeed": true }.

Note on action naming: When registering a subscription, use the past-tense value invoiceCreated in the action field. The events that faktoora actually fires to your endpoint use present tense (e.g., invoiceCreate, invoiceSent). These are different strings — do not confuse them.

Example: Register a webhook

curl -X POST \
  -H "X-API-KEY: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "invoiceCreated",
    "target": "https://your-endpoint.example.com/hook"
  }' \
  https://api.faktoora.com/api/v1/webhooks

Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "action": "invoiceCreated",
  "target": "https://your-endpoint.example.com/hook"
}

The id field is a UUID. Use it in PATCH and DELETE requests.

Example: Update a webhook

curl -X PATCH \
  -H "X-API-KEY: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "invoiceCreated",
    "target": "https://new-endpoint.example.com/hook"
  }' \
  https://api.faktoora.com/api/v1/webhooks/550e8400-e29b-41d4-a716-446655440000

Example: Delete a webhook

curl -X DELETE \
  -H "X-API-KEY: your-api-token" \
  https://api.faktoora.com/api/v1/webhooks/550e8400-e29b-41d4-a716-446655440000

Response (200 OK)

{ "succeed": true }

---

Event Details

invoiceCreate

{
  "faktooraId": "<string>",
  "action": "invoiceCreate",
  "payload": {
    "faktooraId": "<string>",
    "amount": "<number>",
    "outstandingBalance": "<number>",
    "currency": "<string>",
    "invoiceNumber": "<string>",
    "invoiceTypeCode": "<number>",
    "status": "<string>",
    "format": "<string>",
    "issueDate": "<string>",
    "dueDate": "<string>",
    "deliveryDate": "<string>",
    "orderNumber": "<string>",
    "shippingOrderNumber": "<string>",
    "contractNumber": "<string>",
    "assignmentNumber": "<string>",
    "orderReferenceId": "<string>",
    "buyerReferenceId": "<string>",
    "mandateReference": "<string>",
    "projectName": "<string>",
    "totalCosts": "<number>",
    "createdAt": "<string>",
    "detailsPage": "<string>"
  }
}

invoiceOverdue

{
  "trigger": {
    "outputFields": {
      "invoice": { /* full invoice object */ },
      "detailsPage": "<string>"
    }
  }
}

invoiceSent

{
  "action": "invoiceSent",
  "faktooraId": "<string>",
  "payload": {
    "id": "<invoiceId>",
    "faktooraId": "<string>",
    "detailsPage": "<string>"
  }
}

invoiceIncomingCreate

{
  "action": "invoiceIncomingCreate",
  "payload": {
    "id": "<invoiceIncomingId>",
    "importId": "<string>",
    "amount": "<number>",
    "taxAmount": "<number>",
    "outstandingBalance": "<number>",
    "invoiceCurrencyCode": "<string>",
    "invoiceNumber": "<string>",
    "issueDate": "<string>",
    "dueDate": "<string>",
    "paymentDate": "<string>",
    "sellerName": "<string>",
    "type": "<string>",
    "inputType": "<string>",
    "buyerReference": "<string>",
    "isValid": "<boolean>",
    "createdAt": "<string>",
    "detailsPage": "<string>"
  }
}

invoiceIncomingSent

{
  "action": "invoiceIncomingSent",
  "payload": {
    "id": "<invoiceIncomingId>",
    "detailsPage": "<string>"
  }
}

offerCreate

{
  "action": "offerCreate",
  "faktooraId": "<string>",
  "payload": {
    "id": "<offerId>",
    "faktooraId": "<string>",
    "detailsPage": "<string>"
  }
}

offerSent

{
  "action": "offerSent",
  "faktooraId": "<string>",
  "payload": {
    "id": "<offerId>",
    "faktooraId": "<string>",
    "detailsPage": "<string>"
  }
}

letterCreate

{
  "action": "letterCreate",
  "faktooraId": "<string>",
  "payload": {
    "id": "<letterId>",
    "faktooraId": "<string>",
    "detailsPage": "<string>"
  }
}

letterSent

{
  "action": "letterSent",
  "faktooraId": "<string>",
  "payload": {
    "id": "<letterId>",
    "faktooraId": "<string>",
    "detailsPage": "<string>"
  }
}

reminderCreate

{
  "action": "reminderCreate",
  "faktooraId": "<string>",
  "payload": {
    "id": "<reminderId>",
    "faktooraId": "<string>",
    "detailsPage": "<string>"
  }
}

reminderSent

{
  "action": "reminderSent",
  "faktooraId": "<string>",
  "payload": {
    "id": "<reminderId>",
    "faktooraId": "<string>",
    "detailsPage": "<string>"
  }
}

orderConfirmationCreate

{
  "action": "orderConfirmationCreate",
  "faktooraId": "<string>",
  "payload": {
    "id": "<orderConfirmationId>",
    "faktooraId": "<string>",
    "detailsPage": "<string>"
  }
}

orderConfirmationSent

{
  "action": "orderConfirmationSent",
  "faktooraId": "<string>",
  "payload": {
    "id": "<orderConfirmationId>",
    "faktooraId": "<string>",
    "detailsPage": "<string>"
  }
}

customerCreate

{
  "action": "customerCreate",
  "faktooraId": "<string>",
  "payload": {
    "id": "<customerId>",
    "faktooraId": "<string>"
  }
}

productCreate

{
  "action": "productCreate",
  "payload": {
    "id": "<productId>"
  }
}

---

Event Flow Diagram

A high-level sequence for outgoing invoice events: