Webhook

Webhooks allow you to receive real-time notifications when events occur in your Blond organization. You can subscribe to specific events or use a catch-all subscription to receive all events.

Related Documentation

For a comprehensive guide on webhook events and implementation, see Webhook Events Guide.

• Allowed query parameters
• Create a webhook subscription
• Update a webhook subscription
• Retrieve a webhook subscription
• Delete a webhook subscription
• List webhook subscriptions
• Test a webhook subscription
• Webhook Event Types
  • Common Event Patterns
  • Invoice Events
  • Expense Events
  • Catch-All Events
• Webhook Delivery
  • Delivery Guarantees
  • Payload Format
  • Security

Allowed query parameters

Filters

Filter	Type	Description
None	-	No filtering supported

Sorting

None supported

Includes

callLogs

Create a webhook subscription

post

/webhook

Attribute (* required)	Type	Description
event *	String	Event name to subscribe to, or * for all events
url *	String	HTTPS URL to receive webhook notifications

HTTPS Required

All webhook URLs must use HTTPS. HTTP URLs are not supported for security reasons.

Example request

{
    "event": "invoice/created",
    "url": "https://api.example.com/webhooks/strawblond"
}

Example response

// HTTP 201 Created
{
    "id": "v7rnRjBn9o",
    "event": "invoice/created",
    "url": "https://api.example.com/webhooks/strawblond",
    "last_failed_at": null,
    "failed_count": 0,
    "call_logs": []
}

Update a webhook subscription

put

/webhook/{id}

Attribute	Type	Description
event	String	Event name to subscribe to, or * for all events
url	String	HTTPS URL to receive webhook notifications

Example response

// HTTP 200 OK
{
    "id": "v7rnRjBn9o",
    "event": "expense.approved",
    "url": "https://api.example.com/webhooks/strawblond",
    "last_failed_at": null,
    "failed_count": 0,
    "call_logs": []
}

Retrieve a webhook subscription

get

/webhook/{id}

Example response

// HTTP 200 OK
{
    "id": "v7rnRjBn9o",
    "event": "invoice/created",
    "url": "https://api.example.com/webhooks/strawblond",
    "last_failed_at": null,
    "failed_count": 0,
    "call_logs": []
}

Delete a webhook subscription

delete

/webhook/{id}

Example response

// HTTP 204 No Content

List webhook subscriptions

get

/webhook

Example response

// HTTP 200 OK
{
    "data": [
        {
            "id": "v7rnRjBn9o",
            "event": "invoice/created",
            "url": "https://api.example.com/webhooks/strawblond",
            "last_failed_at": null,
            "failed_count": 0,
            "call_logs": []
        },
        {
            "id": "8mApSdTg2k",
            "event": "*",
            "url": "https://api.example.com/webhooks/all-events",
            "last_failed_at": "2024-01-15T10:30:00.000000Z",
            "failed_count": 3,
            "call_logs": []
        }
    ]
}

Test a webhook subscription

post

/webhook/{id}/test

Sends a test webhook event to verify your endpoint is working correctly. This endpoint cannot be used with catch-all (*) webhook subscriptions.

Catch-All Limitation

Test webhooks cannot be sent to catch-all event subscriptions (event: "*"). You must test specific event subscriptions only.

Example response

// HTTP 204 No Content

Webhook Event Types

Webhooks support various event types throughout the Blond system:

Common Event Patterns

• {model}/created (e.g. invoice/created) - When an entity is created
• {model}/updated (e.g. invoice/updated) - When an entity is updated
• {model}/deleted (e.g. invoice/deleted) - When an entity is deleted
• {model}/approved (e.g. offer/approved) - When an entity is approved
• {model}/paid (e.g. invoice/paid) - When an entity is marked as paid

Invoice Events

Besides invoice/created, invoice/updated and invoice/deleted, invoices trigger:

• invoice/sent - When an invoice is sent
• invoice/ready-for-delivery - When a draft invoice reaches its issue date and is ready to be sent
• invoice/reminded - When a payment reminder is sent
• invoice/paid - When an invoice is paid in full
• invoice/cancelled - When an invoice becomes fully cancelled. Cancelling the remainder of a partly paid invoice sends invoice/paid instead.

Expense Events

Besides expense/created, expense/updated and expense/deleted, expenses trigger:

• expense/approved - When a bill is approved for payment
• expense/draft - When a bill is set back to draft
• expense/paid - When a bill is marked as paid, or fully settled with a cash discount or price reduction
• expense/written-off - When the open amount of a bill is written off

Catch-All Events

Use * as the event name to receive all webhook events. This is useful for logging or analytics purposes, but be prepared to handle high volumes of events.

Webhook Delivery

Delivery Guarantees

• Webhooks are delivered with at-least-once semantics
• Failed deliveries are automatically retried with exponential backoff
• Your endpoint should respond with HTTP 200-299 status codes to indicate successful receipt
• Failed webhooks are tracked in the failed_count and last_failed_at fields

Payload Format

All webhook payloads follow this structure:

{
    "id": "<unique-event-id>",
    "event": "<event-type>",
    "created": 1663762684,
    "test": false,
    "data": {
        // The associated object (e.g., invoice, expense)
    }
}

Security

For information on verifying webhook signatures and securing your webhook endpoints, see the Webhook Events Guide.

Development & Testing

For local development, use tools like ngrok or Expose to create secure tunnels to your localhost. See the webhook guide for more details.