Webhooks

Outcome: Receive and verify asynchronous platform events.
Prerequisites: A public HTTPS endpoint that preserves the raw request body.
You'll use: Webhook secret, delivery ID, and event-specific handlers.

Webhooks send HTTP POST requests to your server when events occur, so you don’t need to poll the API for changes.

Quick Start

Create a webhooktypescript

const webhook = await sdk.webhooks.create({
  url: "https://example.com/webhooks",
  events: ["invoice.created", "invoice.paid", "payment.received"],
  description: "Invoice notifications",
});

// Save the secret — it is only shown on creation
console.log("Webhook secret:", webhook.secret);

Event Types

Subscribe to specific events or listen to all events for a category.

Browse the complete event catalog

Invoices

Event	Trigger
`invoice.created`	Invoice created
`invoice.updated`	Invoice updated
`invoice.sent`	Invoice sent to customer
`invoice.paid`	Invoice fully paid
`invoice.overdue`	Invoice past due date
`invoice.cancelled`	Invoice cancelled
`invoice.deleted`	Invoice soft-deleted
`invoice.restored`	Invoice restored from deletion
`invoice.voided`	Invoice voided
`invoice.finalized`	Invoice finalized (locked)

Customers

Event	Trigger
`customer.created`	Customer created
`customer.updated`	Customer updated
`customer.deleted`	Customer soft-deleted
`customer.restored`	Customer restored
`customer.permanently_deleted`	Customer permanently removed

Payments

Event	Trigger
`payment.received`	Payment received
`payment.updated`	Payment updated
`payment.failed`	Payment failed
`payment.deleted`	Payment soft-deleted
`payment.restored`	Payment restored
`payment.permanently_deleted`	Payment permanently removed

Expenses

Event	Trigger
`expense.created`	Expense created
`expense.updated`	Expense updated
`expense.finalized`	Expense finalized (locked)
`expense.voided`	Expense voided
`expense.deleted`	Expense deleted

Estimates

Event	Trigger
`estimate.created`	Estimate created
`estimate.sent`	Estimate sent
`estimate.accepted`	Estimate accepted by customer
`estimate.rejected`	Estimate rejected
`estimate.deleted`	Estimate soft-deleted
`estimate.restored`	Estimate restored

Credit Notes

Event	Trigger
`credit_note.created`	Credit note created
`credit_note.issued`	Credit note issued
`credit_note.voided`	Credit note voided
`credit_note.deleted`	Credit note soft-deleted
`credit_note.restored`	Credit note restored

Advance Invoices

Event	Trigger
`advance_invoice.created`	Advance invoice created
`advance_invoice.paid`	Advance invoice paid
`advance_invoice.applied`	Advance applied to final invoice
`advance_invoice.voided`	Advance invoice voided
`advance_invoice.deleted`	Advance invoice soft-deleted
`advance_invoice.restored`	Advance invoice restored

Expenses

Event	Trigger
`expense.created`	Expense created as a draft or posted expense
`expense.updated`	Expense updated or restored from void
`expense.finalized`	Draft expense finalized and posted
`expense.voided`	Posted expense voided
`expense.deleted`	Draft expense soft-deleted

Recurring Invoices

Event	Trigger
`recurring_invoice.created`	Schedule created
`recurring_invoice.updated`	Schedule updated
`recurring_invoice.deleted`	Schedule soft-deleted
`recurring_invoice.restored`	Schedule restored
`recurring_invoice.permanently_deleted`	Schedule permanently removed
`recurring_invoice.paused`	Schedule paused
`recurring_invoice.resumed`	Schedule resumed
`recurring_invoice.invoice_generated`	Invoice generated from schedule
`recurring_invoice.generation_failed`	Invoice generation failed
`recurring_invoice.completed`	All invoices generated

Items & Taxes

Event	Trigger
`item.created`	Item created
`item.updated`	Item updated
`item.deleted`	Item soft-deleted
`item.restored`	Item restored
`item.permanently_deleted`	Item permanently removed
`tax.created`	Tax created
`tax.updated`	Tax updated
`tax.deleted`	Tax soft-deleted
`tax.restored`	Tax restored
`tax.permanently_deleted`	Tax permanently removed

Orders & Delivery Notes

Event	Trigger
`order.created`	Order created
`order.updated`	Order updated
`order.deleted`	Order soft-deleted
`order.restored`	Order restored
`order.permanently_deleted`	Order permanently removed
`order.processed`	Order processed
`order.cancelled`	Order cancelled
`order.failed`	Order processing failed
`order_integration.created`	Order integration created
`order_integration.updated`	Order integration updated
`order_integration.deleted`	Order integration deleted
`delivery_note.created`	Delivery note created
`delivery_note.sent`	Delivery note sent
`delivery_note.cancelled`	Delivery note cancelled
`delivery_note.voided`	Delivery note voided
`delivery_note.deleted`	Delivery note soft-deleted
`delivery_note.restored`	Delivery note restored

Amazon SES reports what happened to a document email after it was sent. Every event carries { id, type, message_id }: the document ID, its type and the email’s message ID (also stored on the document’s sent activity). email.delivered, email.bounced and email.complained add recipients, the affected addresses; email.bounced also adds bounce_type and bounce_sub_type, and email.complained adds feedback_type. email.opened carries only { id, type, message_id }: SES does not say which recipient opened, and no IP address or user agent is stored.

Event	Trigger
`email.delivered`	The recipient’s mail server accepted the email
`email.bounced`	The email bounced (permanent or temporary)
`email.complained`	The recipient marked the email as spam
`email.opened`	First open of the email; only when the entity enabled `email_open_tracking_enabled`

E-Invoicing & Integrations

The ksef.submission.* events carry { id, type, ksef }: the document ID, its type (invoice or credit_note), and the document’s KSeF state, the same object GET /invoices/{id}/ksef returns.

Event	Trigger
`e_invoicing.submission.created`	E-invoice submitted
`e_invoicing.submission.delivered`	E-invoice delivered
`e_invoicing.submission.failed`	E-invoice delivery failed
`e_invoicing.enrollment.verified`	Entity enrollment verified for e-invoicing
`e_invoicing.enrollment.rejected`	Entity enrollment rejected for e-invoicing
`e_invoicing.supplier.onboarded`	Deprecated compatibility event emitted with `e_invoicing.enrollment.verified`
`e_invoicing.supplier.rejected`	Deprecated compatibility event emitted with `e_invoicing.enrollment.rejected`
`ksef.submission.accepted`	KSeF accepted a Polish invoice or credit note
`ksef.submission.rejected`	KSeF rejected a Polish invoice or credit note
`ksef.submission.upo_available`	The KSeF receipt (UPO) for a document is available to download
`stripe_app.connected`	Stripe app connected
`stripe_app.disconnected`	Stripe app disconnected
`stripe_app.settings_updated`	Stripe app settings changed

Payload Format

Every webhook delivery sends a JSON payload:

{
  "event": "invoice.paid",
  "data": {
    "id": "inv_abc123",
    "number": "INV-001",
    "..."
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

The data field contains the full resource object at the time of the event.

Delivery Headers

Header	Description
`X-Webhook-Signature`	HMAC-SHA256 signature (`sha256=<hex>`)
`X-Webhook-Timestamp`	Unix timestamp (seconds)
`X-Webhook-Event`	Event type
`X-Webhook-Delivery`	Unique delivery ID
`X-Webhook-Id`	Webhook ID
`Content-Type`	`application/json`

Verifying Signatures

Every delivery is signed with your webhook secret using HMAC-SHA256. Always verify signatures to ensure requests are from Space Invoices.

Verify webhook signaturetypescript

import crypto from "node:crypto";

function verifyWebhookSignature(
  secret: string,
  payload: string,
  signatureHeader: string,
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return signatureHeader === `sha256=${expected}`;
}

// In your webhook handler:
const rawBody = await request.text();
const signature = request.headers.get("X-Webhook-Signature")!;

if (!verifyWebhookSignature("your_webhook_secret", rawBody, signature)) {
  throw new Error("Invalid webhook signature");
}

Handling Events

Process events asynchronously and respond quickly with a 2xx status.

Handle webhook eventstypescript

app.post("/webhooks", async (req, res) => {
  const { event, data, timestamp } = req.body;

  switch(event) {
    case "invoice.paid":
      await fulfillOrder(data.id);
      break;
    case "invoice.overdue":
      await sendReminder(data.id);
      break;
    case "customer.created":
      await syncToExternalCRM(data);
      break;
  }

  // Always respond 2xx quickly
  res.status(200).json({ received: true });
});

Retry Policy

Failed deliveries (non-2xx response or timeout) are retried up to 5 times with increasing delays:

Attempt	Delay
1	1 minute
2	5 minutes
3	30 minutes
4	2 hours
5	24 hours

Deliveries that return 410 Gone are not retried and the webhook is automatically deactivated.

The delivery timeout is 10 seconds — your endpoint must respond within this window.

Best Practices

Respond 2xx quickly — Do heavy processing asynchronously after acknowledging the webhook
Verify signatures — Always validate X-Webhook-Signature before processing
Handle duplicates — Use the X-Webhook-Delivery header as an idempotency key in case of retries
Monitor deliveries — Check webhook delivery logs in the dashboard for failures
Use specific events — Subscribe only to events you need rather than all events
Secure your endpoint — Use HTTPS and restrict access to Space Invoices IP ranges if possible