Receiving events (webhooks)

Instead of polling, let Worxley tell you when something changes.

1 min readUpdated 15 Oct 2026API v1

Add an endpoint#

Add an endpoint in Configuration → Marketplace → API & Webhooks → Add endpoint: an https URL on the public internet, and the events you want, or all of them. You get a signing secret once; keep it with your server’s settings.

The payload#

Each event is a POST with a JSON body:

POST https://example.com/worxley-webhook

X-Worxley-Event: deal.stage_changed
X-Worxley-Delivery: 671e3f0c9a8b4c0012ab34cd
X-Worxley-Signature: t=1792065600,v1=5f2c…e91a

{
  "id": "evt_3f9a1c0b7d2e4a6f8b1c0d2e",
  "type": "deal.stage_changed",
  "createdAt": "2026-10-15T09:20:00.000Z",
  "organization": "6a4c3a85c01de391daf2b7fe",
  "data": {
    "object": "deal",
    "id": "6a4c3a85c01de391daf2b9a2",
    "description": "Deal moved to Negotiation",
    "changes": { "before": { "stage": "proposal" }, "after": { "stage": "negotiation" } },
    "actor": { "type": "USER", "id": "…", "channel": "UI" }
  }
}

Events are thin#

Events say what happened to which record and what changed. When you need the whole record, fetch it with GET /deals/{id}. That way you always act on the current data, even when events arrive out of order. Custom record events also carry data.objectSlug.

actor.channel is UI, API, COPILOT or MCP, so you can skip echoes of your own API writes.

Responding#

Answer with any 2xx within 10 seconds. Do the real work in a queue after acknowledging. Redirects aren’t followed. Before trusting a delivery, verify its signature.