Webhooks (receiving events)

Register under Developer → Webhooks in the console: choose the address to receive at and the events to receive. Only administrators with the permission to manage webhooks can do this.

• Only addresses starting with https:// can be registered.
• The signing secret is shown once, when you register. You can rotate it later.

• knowledge.meaning.created — knowledge was created
• knowledge.meaning.updated — knowledge was updated
• workflow.run.completed — a workflow finished
• workflow.run.failed — a workflow failed
• inbound.event.received — an event from an outside service was received

Each notification is JSON with only the fields below. No body text and no personal data are included; read the details afterwards over MCP if you need them.

• id — the notification's identifier (use it to spot a duplicate)
• type — the kind of event (list above)
• occurred_at — when it happened (UTC)
• brand_key — which brand the event belongs to (may be empty)
• object — the target's type and identifier
• api_version — the version of this shape (currently 1)

Each notification carries an X-Cfx-Signature header in the form t=<unix time>,v1=<signature>.

• The signature is the hex HMAC-SHA256 of <t>.<the raw body as received>, keyed with your signing secret.
• Reject a notification whose time t is more than 5 minutes off.
• Right after a secret rotation, two signatures are sent (two v1= values) — the old and the new. If either matches, it is genuine.

• If your endpoint answers with anything other than 2xx, or does not answer within 10 seconds, we retry later (after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours).
• The same notification may arrive twice. Use its id to spot the duplicate and ignore it.
• After 20 failures in a row, the endpoint becomes "Disabled automatically" and receives nothing. Once it is fixed, register it again.