Webhooks

Quick start

1. Create an External API token with webhooks:write and webhooks:read.
2. Register an HTTPS endpoint and choose the events you want.
3. Copy the signing secret returned at creation. It is shown only once.
4. Verify X-ArtyChat-Signature before processing each request.
5. Return any 2xx response within 15 seconds to acknowledge delivery.

curl -X POST https://artychat.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production CRM",
    "url": "https://example.com/webhooks/artychat",
    "events": ["booking.created","booking.status_changed","customer.updated"]
  }'

Supported events

Subscribe to individual events or use * to receive every supported event.

Payload format

Expense events contain data.expense. Delivery events contain data.delivery and data.metadata; status_changed also includes previous_status and status. Delivery payloads omit internal proof storage paths. Delivery events are queued after the database transaction commits and also cover automatic handoff when a POS order becomes ready.

Each delivery has a stable event envelope. The resource-specific object is inside data.

{
  "id": "4a1a2a92-0b3b-4df5-9cb4-b70934af52a1",
  "type": "booking.status_changed",
  "created_at": "2026-10-05T05:10:00.000000Z",
  "business_id": 29,
  "data": {
    "booking": {
      "id": 1234,
      "status": "confirmed"
    },
    "previous_status": "pending",
    "status": "confirmed"
  }
}

Verify webhook signatures

Compute HMAC-SHA256 over timestamp + "." + raw_request_body with your endpoint signing secret. Compare the result using a constant-time comparison.

PHP

$body = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_ARTYCHAT_TIMESTAMP'] ?? '';
$received = $_SERVER['HTTP_X_ARTYCHAT_SIGNATURE'] ?? '';

$expected = 'v1=' . hash_hmac(
    'sha256',
    $timestamp . '.' . $body,
    getenv('ARTYCHAT_WEBHOOK_SECRET')
);

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Invalid signature');
}

http_response_code(200);

Node.js

const crypto = require("crypto");

const expected = "v1=" + crypto
  .createHmac("sha256", process.env.ARTYCHAT_WEBHOOK_SECRET)
  .update(timestamp + "." + rawBody)
  .digest("hex");

if (!crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(signature)
)) {
  return res.status(401).send("Invalid signature");
}

res.sendStatus(200);

Webhook management API

All paths are relative to https://artychat.com/api/v1.

Each business can create up to 20 webhook endpoints. Endpoint URLs must use HTTPS.

Acknowledgements and retries

• Any HTTP 2xx response acknowledges a delivery.
• The endpoint has 15 seconds to respond.
• Failed deliveries are retried automatically up to 5 attempts.
• Retry delays increase progressively: approximately 1 minute, 5 minutes, 15 minutes, and 1 hour.
• Use X-ArtyChat-Delivery as an idempotency key. Your receiver should safely ignore duplicate delivery IDs.

Test an endpoint

curl -X POST https://artychat.com/api/v1/webhooks/1/test \
  -H "Authorization: Bearer YOUR_API_KEY"

Test deliveries use event type webhook.test and the same signing mechanism as production events.

Security recommendations

• Always verify the HMAC signature against the raw request body before parsing or acting on the payload.
• Reject stale timestamps to reduce replay risk. A 5-minute tolerance is a common choice.
• Store signing secrets in a secret manager or environment variable.
• Rotate a signing secret immediately if you suspect it was exposed.
• Return quickly, then perform slow processing asynchronously in your own queue.
• Do not assume delivery order. Use event timestamps and resource IDs when sequencing matters.