--- url: https://docs.codefox.ai/connect/events.md --- # Receive suite events by webhook This page lets you send a signed message to a system of yours whenever something happens in a Foxden app: a lead is created, a deal moves, a meeting ends, a document is signed, a call ends. You add the destination in Foxden Admin, then verify each message where it arrives. ## Which apps send events Four apps send events to Admin, which passes them on to your destinations: | App | Events | |---|---| | Fennec | `fennec.lead.created`, `fennec.deal.stage_changed` | | Arctic | `arctic.meeting.ended` | | Corsac | `corsac.document.completed` | | Cape | `cape.call.ended`, `cape.call.deleted` | Pampas, Culpeo and Library send no suite events. What each event means and the ids it carries are in [Events](/reference/events). An event carries ids only, never names, text or transcripts. To act on one, read the record through the app's API or through [the AI gateway](/connect/gateway) with an [agent identity](/connect/agent-identities). ## Before you start * You are an Owner in Admin. The Events page is for Owners only. * You have an https address that accepts a POST. Private and internal addresses are refused unless the person who runs the server has allowed them. ## Add a destination 1. In Admin, open **Workspace** › **Assistants**, then **Events**. 2. Select **Add a destination**. 3. Fill in **Name** and **Web address to send to**. 4. Leave **Signing secret** blank to have one made for you, or type your own of at least 16 characters. 5. Under **Which events to send (tick none to send them all)**, tick the events you want. 6. Select **Add destination**. If Admin made the secret, it is shown once: store it now. The destination appears under **Where events are sent**. You can **Pause**, **Resume** or **Delete** it there. A company can have at most 50 destinations. While no destination exists, events are still received and kept for seven days, but sent nowhere. An Owner's assistant can do the same with the `admin_create_event_subscription`, `admin_list_event_subscriptions` and `admin_delete_event_subscription` tools. ## What a delivery looks like Each event is one POST with a JSON body: ```json { "v": 1, "id": "a1b2c3d4e5f6a7b8", "type": "corsac.document.completed", "product": "corsac", "occurredAt": "2026-11-19T10:42:07.120Z", "orgId": null, "subject": { "documentId": "" }, "data": { "recipientCount": 2 } } ``` `orgId` is the sending app's own id for the company, or null. `subject` holds the record ids, and `data` the few facts the event carries. The request carries these headers: | Header | Value | |---|---| | `content-type` | `application/json` | | `x-codefox-event-id` | The event's id | | `x-codefox-event-type` | The event's type | | `x-codefox-timestamp` | When it was signed, in Unix seconds | | `x-codefox-signature` | `sha256=` and the hex HMAC-SHA256 of `.`, keyed with your signing secret | ## Verify a delivery Check every message before you trust it: 1. Read the raw body as bytes, before any JSON parsing. A re-serialised body does not match the signature. 2. Refuse the message if `x-codefox-timestamp` is more than 300 seconds from your clock. 3. Compute the HMAC-SHA256 of the timestamp, a dot, and the raw body, with your secret, and compare it with `x-codefox-signature` in constant time. 4. Store the event id, and ignore an id you have already handled: the same event can arrive more than once. In Node.js: ```js import { createHmac, timingSafeEqual } from "node:crypto"; export function verify(rawBody, headers, secret) { const ts = headers["x-codefox-timestamp"]; const sig = headers["x-codefox-signature"] ?? ""; if (!/^\d+$/.test(ts ?? "")) return false; if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; const expected = "sha256=" + createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex"); const a = Buffer.from(expected); const b = Buffer.from(sig); return a.length === b.length && timingSafeEqual(a, b); } ``` Answer with any 2xx status once the message is stored. ## Retries A delivery that gets no 2xx is tried again, eight attempts in all: after about 30 seconds, 2 minutes, 8 minutes and 32 minutes, then hourly, about four hours of trying. A `Retry-After` header you send is honoured. Each attempt waits 10 seconds for an answer. A 4xx answer other than 408, 425 or 429 tells Admin you refuse the message, and it stops trying. Admin's bell tells the Owner when a destination gives up. **What was sent**, on the Events page, lists the latest deliveries with their status, the number of tries and the last result. ## Corsac's own webhooks Corsac also sends webhooks of its own, with more detail about each document (sent, viewed, signed, declined, voided, expired, sealed). They are set up in Corsac, not in Admin, and signed differently: `X-Corsac-Signature: sha256=` over the raw body, with no timestamp. See [Use the Corsac API](/connect/corsac-api#get-told-when-something-changes). ## Troubleshooting ### Adding a destination says "The URL must be https." Use an https address. Plain http is accepted only for private addresses the server's operator allowed. ### Adding a destination says "That address is not allowed" The address points at a private or internal network. Use a public address, or ask the person who runs the server to allow that private address. ### Every delivery fails with a signature error on your side You are probably verifying a parsed and re-serialised body. Verify the raw bytes as they arrived.