Webhooks Overview

Koteshen webhooks allow you to receive real-time notifications for key events in your invoicing workflow, such as invoice creation, updates, sending, payments, and overdue status changes. Webhooks are delivered as HTTP POST requests to a URL you specify, with a JSON payload containing event details.

Key Concepts

• Events: Webhooks are triggered by specific events (e.g., invoice.created). You subscribe to events when creating a webhook endpoint.
• Subscriptions: Manage webhook endpoints via the API to subscribe/unsubscribe from events and configure delivery URLs.
• Security: Each webhook includes a secret for signature verification. Use the X-Koteshen-Signature header (HMAC SHA256 of the payload using your secret) to validate requests.
• Retries: Failed deliveries (non-2xx responses) are retried up to 5 times with exponential backoff (1min, 5min, 15min, 1hr, 3hr).
• Payload: All payloads include event (string), data (event-specific object), and occurred_at (ISO 8601 timestamp).
• API Version: Webhooks use v1 payloads unless specified otherwise.

Supported Events

Event Payload Examples

invoice.created

{
  "event": "invoice.created",
  "data": {
    "id": 150,
    "number": "INV-8E5E-2268",
    "customer_id": 13,
    "currency": "USD",
    "total": { "cents": 43700, "currency_iso": "USD" },
    "status": "created",
    "issued_at": "2025-10-12T00:00:00.000Z",
    "due_at": "2025-10-12T00:00:00.000Z"
    // Full invoice object (see Show Invoice docs for structure)
  },
  "occurred_at": "2025-10-21T03:39:57.913Z"
}

invoice.updated

{
  "event": "invoice.updated",
  "data": {
    "id": 150,
    "number": "INV-8E5E-2268",
    // Changes only (diff from previous state)
    "status": "sent", // Example change
    "updated_at": "2025-10-21T04:00:00.000Z"
    // Full updated invoice object
  },
  "occurred_at": "2025-10-21T04:00:00.000Z"
}

invoice.sent

{
  "event": "invoice.sent",
  "data": {
    "id": 150,
    "number": "INV-8E5E-2268",
    "emailed_at": "2025-10-21T04:00:00.000Z"
    // Full invoice object
  },
  "occurred_at": "2025-10-21T04:00:00.000Z"
}

invoice.paid

{
  "event": "invoice.paid",
  "data": {
    "id": 150,
    "number": "INV-8E5E-2268",
    "balance": { "cents": 0, "currency_iso": "USD" }, // Updated balance
    "payments": [
      {
        "id": 37,
        "reference": "Payment 123",
        "amount": { "cents": 34000, "currency_iso": "USD" },
        "paid_at": "2025-10-12T00:00:00.000Z"
      }
    ]
    // Full invoice object
  },
  "occurred_at": "2025-10-21T04:41:11.901Z"
}

invoice.overdue

{
  "event": "invoice.overdue",
  "data": {
    "id": 150,
    "number": "INV-8E5E-2268",
    "due_at": "2025-10-12T00:00:00.000Z",
    "balance": { "cents": 43700, "currency_iso": "USD" }
    // Full invoice object
  },
  "occurred_at": "2025-10-21T10:00:00.000Z" // When overdue check runs
}

Managing Subscriptions

Use the endpoints below to create, view, update, and delete webhook subscriptions. Each subscription targets a specific URL and set of events.

POST /api/v1/webhook_endpoints

Create a new webhook endpoint subscription.

Path Parameters

None.

Request Body

Example Request

{
  "url": "https://your-app.com/webhooks/koteshen",
  "enabled_events": [
    "invoice.created",
    "invoice.updated",
    "invoice.sent",
    "invoice.paid",
    "invoice.overdue"
  ]
}

Response

Response Body

{
  "data": {
    "id": 1,
    "url": "https://koteshen.com/api/v1/webhook_endpoints/1.json",
    "enabled_events": [
      "invoice.created",
      "invoice.updated",
      "invoice.sent",
      "invoice.paid",
      "invoice.overdue"
    ],
    "secret": "7410cb06136ce53dd5c5f7a270f5652743e1f17c",
    "api_version": "v1",
    "enabled": true,
    "created_at": "2025-10-17T23:56:10.396Z",
    "updated_at": "2025-10-18T05:12:54.125Z"
  }
}

• secret: Use this to verify incoming webhook signatures. Keep it secure—it’s shown only once on creation.
• enabled: Defaults to true. Set to false to pause deliveries without deleting.

Error Responses

Usage Notes

• Limit: Up to 10 active subscriptions per business.
• HTTPS only: URLs must use HTTPS.
• Verification: On creation, a test ping event may be sent to validate the URL.

GET /api/v1/webhook_endpoints

List all webhook endpoint subscriptions.

Path Parameters

None.

Query Parameters

Example Request

GET /api/v1/webhook_endpoints?page=1&per_page=5

Response

Response Body

{
  "data": [
    {
      "id": 1,
      "url": "https://your-app.com/webhooks/koteshen",
      "enabled_events": ["invoice.created", "invoice.paid"],
      "secret": "7410cb06136ce53dd5c5f7a270f5652743e1f17c", // Omitted for security in lists
      "api_version": "v1",
      "enabled": true,
      "created_at": "2025-10-17T23:56:10.396Z",
      "updated_at": "2025-10-18T05:12:54.125Z"
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "total_pages": 1,
      "total_count": 1
    }
  },
  "links": {
    "self": "https://koteshen.com/api/v1/webhook_endpoints?page=1",
    "first": "https://koteshen.com/api/v1/webhook_endpoints?page=1",
    "last": "https://koteshen.com/api/v1/webhook_endpoints?page=1"
  }
}

Error Responses

GET /api/v1/webhook_endpoints/{id}

Retrieve a specific webhook endpoint subscription.

Path Parameters

Example Request

GET /api/v1/webhook_endpoints/1

Response

Response Body

{
  "data": {
    "id": 1,
    "url": "https://your-app.com/webhooks/koteshen",
    "enabled_events": ["invoice.created", "invoice.paid"],
    "secret": "7410cb06136ce53dd5c5f7a270f5652743e1f17c",
    "api_version": "v1",
    "enabled": true,
    "created_at": "2025-10-17T23:56:10.396Z",
    "updated_at": "2025-10-18T05:12:54.125Z"
  }
}

Error Responses

PATCH /api/v1/webhook_endpoints/{id}

Update an existing webhook endpoint subscription.

Path Parameters

Request Body

Example Request

{
  "enabled_events": ["invoice.created", "invoice.overdue"],
  "enabled": true
}

Response

Response Body Same as GET /api/v1/webhook_endpoints/{id}.

Error Responses

DELETE /api/v1/webhook_endpoints/{id}

Delete a webhook endpoint subscription.

Path Parameters

Example Request

DELETE /api/v1/webhook_endpoints/1

Response

Error Responses

Usage Notes

• Deleting a subscription stops all deliveries immediately.
• No undo—use PATCH to disable instead if needed.

Integration Tips

1. Verification Code: Compute HMAC-SHA256(payload, secret) and compare to X-Koteshen-Signature header.
2. Idempotency: Use occurred_at and event IDs to deduplicate.
3. Testing: Use tools like webhook.site for initial setup. Trigger test events via API (e.g., create an invoice).
4. Rate Limits: Webhooks are rate-limited per subscription (1000/min).
5. Support: For issues, contact support@koteshen.com with subscription ID and event samples.

For full API reference, see Invoices, Customers, etc.