Webhooks

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

Copy

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);

Webhooks API →

Caution

The webhook secret is only returned when the webhook is created or the secret is rotated. Store it securely.

Event Types

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

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.failed	Payment failed
payment.deleted	Payment soft-deleted
payment.restored	Payment restored
payment.permanently_deleted	Payment permanently removed

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

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.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

E-Invoicing & Integrations

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.supplier.onboarded	Supplier onboarded for e-invoicing
e_invoicing.supplier.rejected	Supplier onboarding rejected
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

Copy

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

Copy

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

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