Webhooks

Webhooks

Webhook endpoint management for receiving real-time event notifications. Configure URLs, select events, and monitor delivery status.

Endpoints

IntroductionPOST/webhooksGET/webhooksGET/webhooks/{id}PATCH/webhooks/{id}DELETE/webhooks/{id}POST/webhooks/{id}/testGET/webhooks/{id}/deliveriesPOST/webhooks/{id}/rotate-secret

Event types

Subscribe to any combination of these events:

Category	Events
Invoices	invoice.created invoice.updated invoice.sent invoice.paid invoice.overdue invoice.cancelled
Customers	customer.created customer.updated customer.deleted
Payments	payment.received payment.failed
Estimates	estimate.created estimate.sent estimate.accepted estimate.rejected
Credit notes	credit_note.created credit_note.issued
Advance invoices	advance_invoice.created advance_invoice.paid advance_invoice.applied

Payload format

Every webhook delivery sends a JSON body with this structure:

{
  "event": "invoice.created",
  "data": { ... },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Delivery headers

Each delivery includes these headers:

Header	Description
X-Webhook-Signature	HMAC-SHA256 signature: sha256=<hex>
X-Webhook-Timestamp	Unix timestamp (seconds) when the payload was signed
X-Webhook-Event	Event type (e.g. invoice.created)
X-Webhook-Delivery	Unique delivery attempt ID
X-Webhook-Id	Webhook endpoint ID
User-Agent	SpaceInvoices-Webhook/1.0

Verifying signatures

Signatures use HMAC-SHA256. To verify:

1. Get the raw request body (do not parse it first)
2. Compute HMAC-SHA256(secret, body) using your webhook secret
3. Compare the hex digest with the value after sha256= in X-Webhook-Signature

const crypto = require('crypto');

function verifySignature(secret, payload, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === `sha256=${expected}`;
}

Retry policy

Failed deliveries are retried up to 5 attempts with exponential backoff:

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

Webhooks are automatically disabled after all retry attempts are exhausted, and an email notification is sent to the entity owner.

HTTP status codes 400, 401, 403, 404, 405, and 410 are treated as permanent failures and are not retried.

The Webhook object

object

Attributes

idstring

urlstring

eventsarray of strings

descriptionstring

activeboolean

secretstring

Masked secret (only shown on create and rotate)

metadataobject

Default: {}

Other attributesExpand all

entity_idstring

created_atstring<date-time>

updated_atstring<date-time>

Examplejson

Copy

{
  "id": "whk_6595a27b5d35015c3ef0c3fd",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "url": "https://example.com/webhooks",
  "description": null,
  "secret": "whsec_****...****",
  "events": [
    "invoice.created",
    "invoice.paid"
  ],
  "active": true,
  "metadata": {},
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z"
}

---

Create a new webhook

POST/webhooks

Create a webhook endpoint. The response includes the full secret which is only visible on creation and when rotated.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Body parameters

urlstring<uri>required

The HTTPS URL to send webhook events to. Cannot target localhost, private IPs, or internal domains.

eventsarray of stringsrequired

Events that trigger this webhook

descriptionstringoptional

Optional description for this webhook

activebooleanoptional

Whether webhook is active

Default: true

metadataobjectoptional

Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

curl -X POST "https://eu.spaceinvoices.com/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks",
    "events": [
      "invoice.created"
    ]
  }'

Example:

MinimalComplete

Response

Returns

idstring

urlstring

eventsarray of strings

descriptionstring

activeboolean

secretstring

metadataobject

Default: {}

Other parametersExpand all

entity_idstring

created_atstring<date-time>

updated_atstring<date-time>

json

Copy

{
  "id": "whk_6595a27b5d35015c3ef0c3fd",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "url": "https://example.com/webhooks",
  "description": null,
  "secret": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "events": [
    "invoice.created",
    "invoice.paid"
  ],
  "active": true,
  "metadata": {},
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z"
}

---

List all webhooks

GET/webhooks

Retrieve a paginated list of webhooks for the entity. Secrets are masked in the response.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Query parameters

limitintegeroptional

Number of results per request.

Default: 10

next_cursorstringoptional

Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.

prev_cursorstringoptional

Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response.

include_total_countbooleanoptional

Whether to include the total count of items in pagination.total.
Default is true.
When false, pagination.total returns -1 for better performance.

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

curl "https://eu.spaceinvoices.com/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID"

Response

Returns

dataarray of objectsShow child attributes

paginationobjectShow child attributes

Pagination metadata including cursors and result counts

json

Copy

{
  "data": [
    {
      "id": "whk_6595a27b5d35015c3ef0c3fd",
      "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
      "url": "https://example.com/webhooks",
      "description": null,
      "secret": "whsec_****...****",
      "events": [
        "invoice.created",
        "invoice.paid"
      ],
      "active": true,
      "metadata": {},
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "next_cursor": null,
    "prev_cursor": null,
    "has_more": false
  }
}

---

Get a webhook by ID

GET/webhooks/{id}

Retrieve a single webhook. The secret is masked in the response.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Path parameters

idstring<resource-id>required

Unique resource identifier

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

curl "https://eu.spaceinvoices.com/webhooks/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID"

Response

Returns

idstring

urlstring

eventsarray of strings

descriptionstring

activeboolean

secretstring

Masked secret (only shown on create and rotate)

metadataobject

Default: {}

Other parametersExpand all

entity_idstring

created_atstring<date-time>

updated_atstring<date-time>

json

Copy

{
  "id": "whk_6595a27b5d35015c3ef0c3fd",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "url": "https://example.com/webhooks",
  "description": null,
  "secret": "whsec_****...****",
  "events": [
    "invoice.created",
    "invoice.paid"
  ],
  "active": true,
  "metadata": {},
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z"
}

---

Update a webhook

PATCH/webhooks/{id}

Update webhook URL, events, active status, or description.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Path parameters

idstring<resource-id>required

Unique resource identifier

Body parameters

urlstring<uri>optional

The HTTPS URL to send webhook events to. Cannot target localhost, private IPs, or internal domains.

eventsarray of stringsoptional

descriptionstringoptional

activebooleanoptional

metadataobjectoptional

Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

curl -X PATCH "https://eu.spaceinvoices.com/webhooks/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://new-url.example.com/webhooks"
  }'

Example:

UpdateUrlUpdateEvents

Response

Returns

idstring

urlstring

eventsarray of strings

descriptionstring

activeboolean

secretstring

Masked secret (only shown on create and rotate)

metadataobject

Default: {}

Other parametersExpand all

entity_idstring

created_atstring<date-time>

updated_atstring<date-time>

json

Copy

{
  "id": "whk_6595a27b5d35015c3ef0c3fd",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "url": "https://example.com/webhooks",
  "description": null,
  "secret": "whsec_****...****",
  "events": [
    "invoice.created",
    "invoice.paid"
  ],
  "active": true,
  "metadata": {},
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z"
}

---

Delete a webhook

DELETE/webhooks/{id}

Permanently delete a webhook endpoint. Pending deliveries will be cancelled.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Path parameters

idstring<resource-id>required

Unique resource identifier

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

curl -X DELETE "https://eu.spaceinvoices.com/webhooks/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID"

Response

Returns

successboolean

json

Copy

{
  "success": true
}

---

Test a webhook

POST/webhooks/{id}/test

Send a test event to the webhook endpoint to verify connectivity.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Path parameters

idstring<resource-id>required

Unique resource identifier

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

curl -X POST "https://eu.spaceinvoices.com/webhooks/{id}/test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID"

Response

Returns

idstring

Other parametersExpand all

webhook_idstring

entity_idstring

event_typestring

statusstring

request_bodyobject

response_statusinteger

response_bodystring

error_messagestring

attemptinteger

max_attemptsinteger

next_retry_atstring<date-time>

duration_msinteger

created_atstring<date-time>

completed_atstring<date-time>

json

Copy

{
  "id": "whd_6595a27b5d35015c3ef0c3fd",
  "webhook_id": "whk_6595a27b5d35015c3ef0c3fd",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "event_type": "webhook.test",
  "status": "success",
  "request_body": {
    "event": "webhook.test",
    "data": {}
  },
  "response_status": 200,
  "response_body": "OK",
  "error_message": null,
  "attempt": 1,
  "max_attempts": 1,
  "next_retry_at": null,
  "duration_ms": 150,
  "created_at": "2024-01-01T00:00:00.000Z",
  "completed_at": "2024-01-01T00:00:00.150Z"
}

---

List webhook deliveries

GET/webhooks/{id}/deliveries

Retrieve a paginated list of delivery attempts for a specific webhook.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Path parameters

idstring<resource-id>required

Unique resource identifier

Query parameters

limitintegeroptional

Number of results per request.

Default: 10

next_cursorstringoptional

Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.

prev_cursorstringoptional

Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response.

include_total_countbooleanoptional

Whether to include the total count of items in pagination.total.
Default is true.
When false, pagination.total returns -1 for better performance.

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

curl "https://eu.spaceinvoices.com/webhooks/{id}/deliveries" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID"

Response

Returns

dataarray of objectsShow child attributes

paginationobjectShow child attributes

Pagination metadata including cursors and result counts

json

Copy

{
  "data": [
    {
      "id": "whd_6595a27b5d35015c3ef0c3fd",
      "webhook_id": "whk_6595a27b5d35015c3ef0c3fd",
      "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
      "event_type": "invoice.created",
      "status": "success",
      "request_body": {
        "event": "invoice.created",
        "data": {
          "id": "inv_123"
        }
      },
      "response_status": 200,
      "response_body": "OK",
      "error_message": null,
      "attempt": 1,
      "max_attempts": 5,
      "next_retry_at": null,
      "duration_ms": 120,
      "created_at": "2024-01-01T00:00:00.000Z",
      "completed_at": "2024-01-01T00:00:00.120Z"
    }
  ],
  "pagination": {
    "total": 1,
    "next_cursor": null,
    "prev_cursor": null,
    "has_more": false
  }
}

---

Rotate webhook secret

POST/webhooks/{id}/rotate-secret

Generate a new signing secret for the webhook. The previous secret is immediately invalidated.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Path parameters

idstring<resource-id>required

Unique resource identifier

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

curl -X POST "https://eu.spaceinvoices.com/webhooks/{id}/rotate-secret" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID"

Response

Returns

idstring

urlstring

eventsarray of strings

descriptionstring

activeboolean

secretstring

metadataobject

Default: {}

Other parametersExpand all

entity_idstring

created_atstring<date-time>

updated_atstring<date-time>

json

Copy

{
  "id": "whk_6595a27b5d35015c3ef0c3fd",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "url": "https://example.com/webhooks",
  "description": null,
  "secret": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "events": [
    "invoice.created",
    "invoice.paid"
  ],
  "active": true,
  "metadata": {},
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z"
}

---