Receive changes as they happen
Subscribe an HTTPS endpoint to exact events or resource wildcards, then verify every delivery before processing it.
Subscribe instead of polling
Load the customer list once, then keep your local copy current withcustomer.created and customer.updated. Register the subscription before loading the list and buffer incoming deliveries during the initial load. Upsert records by their public ID and deduplicate deliveries.
GET /api/v1/customers?limit=100
# Follow every pagination cursor. Save the sync start time as your checkpoint.
# After an outage, replay changes from that checkpoint:
GET /api/v1/customers?updatedAfter=2026-10-29T08:00:00.000Z&limit=100After an outage, use updatedAfter to catch up and follow all pagination cursors before advancing your checkpoint. Customers, projects, tasks and documents support this filter. For customer requests, reload the full list to recover board changes: moving cards and renaming columns do not change the request timestamp. Reload the full member list after an outage.
Subscribe to customer_request.* for created, updated, converted and archived requests. Updated events contain the full public record and fire only when public fields change. The nullable lostAt field records a loss and becomes null on reopening; both changes emit an update. Subscribe to member.* for created, updated and deactivated memberships. Reactivation is an update; account name changes produce an update in each organization where the membership and account remain active. Former members and support access are excluded. Consecutive changes may be coalesced before delivery; payloads reflect the public record at dispatch time.
Subscribe to payment.created for every payment or correction booked on an invoice, in craftivo or through the API. The delivery carries the payment and the invoice state after the booking. invoice.partially_paid and invoice.paid fire only when the invoice status changes; a second partial payment sends invoice.updated instead.
Create a subscription
Register a public HTTPS endpoint with the events it should receive. You can subscribe to exact names such as customer.created, resource wildcards such asinvoice.*, or * for all events.
curl --request POST \
--url "https://quick-goldfinch-475.eu-west-1.convex.site/api/v1/webhooks" \
--header "Authorization: Bearer $CRAFTIVO_API_KEY" \
--header "X-Organization-Id: $CRAFTIVO_ORGANIZATION_ID" \
--header "Idempotency-Key: webhook-setup-001" \
--header "Content-Type: application/json" \
--data '{
"url": "https://example.com/webhooks/craftivo",
"events": ["customer.created", "invoice.*"]
}'Delivery format
craftivo sends a JSON POST request. The delivery ID stays stable across retries, so it can also be used for deduplication.
Content-Type: application/json
X-Webhook-Event: customer.created
X-Webhook-Delivery: delivery_…
X-Webhook-Timestamp: 1786291200
X-Webhook-Signature: 7f1c…When the event or a field of its payload is deprecated, the delivery also carries Deprecation. Sunset comes only when the whole event is deprecated and may go away; a deprecated field gets none.
{
"id": "event_…",
"event": "customer.created",
"createdAt": 1786291200000,
"data": {
"customer": {
"id": "customer_…",
"name": "Müller Haustechnik GmbH"
}
}
}Verify the HMAC signature
Compute a hex HMAC-SHA256 over <timestamp>.<raw body>using the endpoint secret. Use the exact raw request body before JSON parsing, reject old timestamps, and compare equal-length buffers in constant time.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyCraftivoWebhook(input: {
rawBody: string;
timestamp: string;
signature: string;
secret: string;
}): boolean {
const { rawBody, timestamp, signature, secret } = input;
const timestampSeconds = Number(timestamp);
if (
!Number.isFinite(timestampSeconds) ||
Math.abs(Date.now() / 1000 - timestampSeconds) > 300
) {
return false;
}
const expected = Buffer.from(
createHmac("sha256", secret)
.update(`${timestamp}.${rawBody}`)
.digest("hex"),
"hex",
);
const received = Buffer.from(signature, "hex");
return (
received.length === expected.length &&
timingSafeEqual(received, expected)
);
}Retries and automatic disabling
Each request times out after 10 seconds. A non-2xx response, redirect, timeout, or network error is retried up to five times after 1 minute, 5 minutes, 15 minutes, 1 hour, and 6 hours. Delivery order is not guaranteed across retries. Order received events by the bodycreatedAt value, not by arrival time, and deduplicate usingX-Webhook-Delivery, which stays stable across retries.
After ten final delivery failures in a row, the endpoint is disabled. HTTP 410 disables it immediately. Disabled endpoints receive nothing until they are reactivated.