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.
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 with an agent identity.
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
- In Admin, open Workspace › Assistants, then Events.
- Select Add a destination.
- Fill in Name and Web address to send to.
- Leave Signing secret blank to have one made for you, or type your own of at least 16 characters.
- Under Which events to send (tick none to send them all), tick the events you want.
- 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:
{
"v": 1,
"id": "a1b2c3d4e5f6a7b8",
"type": "corsac.document.completed",
"product": "corsac",
"occurredAt": "2026-11-19T10:42:07.120Z",
"orgId": null,
"subject": { "documentId": "<the document's id>" },
"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 <timestamp>.<raw body>, keyed with your signing secret |
Verify a delivery
Check every message before you trust it:
- Read the raw body as bytes, before any JSON parsing. A re-serialised body does not match the signature.
- Refuse the message if
x-codefox-timestampis more than 300 seconds from your clock. - Compute the HMAC-SHA256 of the timestamp, a dot, and the raw body, with your secret, and compare it with
x-codefox-signaturein constant time. - Store the event id, and ignore an id you have already handled: the same event can arrive more than once.
In Node.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=<hex> over the raw body, with no timestamp. See Use the Corsac API.
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.