Webhooks and events
Get told when something happens in Venom. Add an org webhook endpoint, pick its events, verify the signature, handle retries, and see every event type each product sends.
Venom sends events to your HTTPS endpoint as signed JSON POSTs. An org has one set of endpoints for every product: each endpoint picks the event types it wants. Nothing is sent until an owner or admin adds an endpoint.
Add an endpoint
In the console, Settings, Webhooks: add an https URL, pick its events, and copy the signing secret. The secret is
shown once, when the endpoint is made or its secret rotated. An org has at most 10 endpoints. Reading the endpoints
needs audit:read; changing them needs org:manage.
From code:
- The admin API,
POST /api/admin/v1/webhooks, creates one with an admin key (Admin API: webhooks). - The
admin_webhook_*tools and their REST routes list, change, test and delete endpoints and retry deliveries (Build on Admin and the mesh). Creating an endpoint and rotating its secret are left to a person on purpose, because the secret is shown once.
A new endpoint gets what happens after it is added; nothing older is sent.
What a delivery looks like
POST /your/endpoint HTTP/1.1
content-type: application/json
user-agent: venom-cloud-webhooks/1
venom-signature: t=1762675200,v1=5f2c…
venom-event: tasks.issue.updated
venom-event-id: 0193…
venom-delivery: 0193…{ "id": "0193…", "type": "tasks.issue.updated", "created_at": "2026-11-09T10:00:00.000Z",
"org": { "id": "org_…" },
"data": { "identifier": "ENG-12", "title": "Ship the launch", "state": "In Review" },
"links": { "issue": "https://cloud.usevenom.dev/tasks/issue/ENG-12" } }idis the event's id: the same on every retry of it, so use it to drop duplicates.datacarries ids, names, numbers and states. It never carries a key, a secret, request content, an issue's description, a comment's text or a note's body. Personal notes and Tasks rows only their owner sees never leave.linkspoints at the thing in the console.
Verify the signature
venom-signature is t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the endpoint's secret>. Check
it over the raw body, before you parse it, and refuse a t more than 5 minutes from your clock.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(secret: string, header: string | null, rawBody: string, toleranceS = 300): boolean {
if (!header) return false;
const parts = header.split(",").map((p) => p.trim().split("="));
const t = Number(parts.find(([k]) => k === "t")?.[1]);
if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceS) return false;
const want = Buffer.from(createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"));
return parts.some(([k, v]) => k === "v1" && v?.length === want.length && timingSafeEqual(Buffer.from(v), want));
}import hashlib, hmac, time
def verify(secret: str, header: str | None, raw_body: bytes, tolerance_s: int = 300) -> bool:
if not header:
return False
parts = [p.strip().split("=", 1) for p in header.split(",")]
t = next((v for k, v in parts if k == "t"), None)
if t is None or not t.isdigit() or abs(time.time() - int(t)) > tolerance_s:
return False
want = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return any(k == "v1" and hmac.compare_digest(v, want) for k, v in parts)Retries
Answer with any 2xx within 5 seconds. Only the first 4 KiB of your answer is read. Anything else is a failure, and
the delivery is tried again after 1, 2, 4, … up to 128 minutes (with ±20 % jitter), 9 attempts in all, about four
hours; then it is marked failed. The delivery log in Settings, Webhooks shows each attempt, with Retry (a fresh set of
attempts) and Send test (one webhook.test event, never retried). Events and deliveries are kept 30 days.
In production the URL must be public https. The cloud checks every address the name resolves to when it connects, refuses private, loopback and metadata addresses, and does not follow redirects.
How events are made
- Tasks and Notes events come from each product's change log, read once a minute. Several changes to one issue or
note within that minute arrive as one event with the thing as it is now, so live typing in a note is one
globe.note.updateda minute. - Spend, key and daemon events are sent once per thing and window (once a month per cap, once per budget and window), so a receiver is not flooded.
Every event type
97 event types, generated from lib/webhooks/events.ts.
| Event | Product | When |
|---|---|---|
spend_cap.warning |
Admin and mesh | The org's month-to-date spend reached 80 % of its monthly cap (once a month per cap). |
spend_cap.reached |
Admin and mesh | The monthly cap is reached and requests are refused with 429 spend_cap_reached. |
budget.warning |
Admin and mesh | A member, key, team or gear budget reached its warning share of the limit (once per budget and window). |
budget.reached |
Admin and mesh | A budget is at its limit: requests are refused with 429 spend_limit_reached, or sent to its cheaper model (once per budget and window). |
spend.threshold |
Admin and mesh | A budget's or the monthly cap's spend passed one of the org's alert thresholds (50, 80, 100 % by default; once per threshold and window). |
spend.forecast |
Admin and mesh | At the current rate a budget or the monthly cap runs out before its window ends (once per window and limit). |
spend.anomaly |
Admin and mesh | A key, member, model or gear spent far above its usual for the hour (robust hourly baseline, the org's floor and sensitivity), with the top requests and keys and a link to pause the key. |
key.expiring |
Admin and mesh | An API key expires within 7 days (once per key and expiry). |
key.expired |
Admin and mesh | An API key passed its expiry and no longer works. |
daemon.offline |
Admin and mesh | A daemon stopped heartbeating: its lease lapsed more than 2 minutes ago. |
daemon.online |
Admin and mesh | A daemon reported offline is heartbeating again. |
autoscale.machine_added |
Admin and mesh | A pool asked its GPU cloud for a machine (demand, its floor or schedule, or Scale to N). |
autoscale.machine_joined |
Admin and mesh | A pool's machine booted and its daemon joined the org. |
autoscale.machine_draining |
Admin and mesh | A pool's machine stopped taking new requests before it is removed (idle, or scaled down). |
autoscale.machine_removed |
Admin and mesh | A pool's machine was terminated at its GPU cloud, or vanished there. |
autoscale.join_timeout |
Admin and mesh | A pool's machine did not join in time and was terminated; check the image and boot log. |
autoscale.machine_interrupted |
Admin and mesh | A GPU cloud reclaimed a pool's spot or preemptible machine; its jobs were requeued and a replacement launched elsewhere. |
autoscale.cap_reached |
Admin and mesh | A pool's estimated GPU spend reached its monthly cap; it adds no machines until next month. |
prompt_filter.blocked |
Admin and mesh | A prompt filter refused a request (at most once per rule and key every 10 minutes). |
quality.degraded |
Admin and mesh | Scheduled quality checks found a significant drop in a model's score or a rise in its latency on a suite. |
quality.recovered |
Admin and mesh | A model flagged degraded is back near its baseline on that suite. |
prompt_filter.response_blocked |
Admin and mesh | A response filter stopped a model's answer mid-way (at most once per rule and key every 10 minutes). |
chargeback.statement |
Admin and mesh | Last month's spend per team, project, gear, key or member, sent on the 1st (UTC) when the monthly statement is on (Usage, Chargeback). |
handoff.created |
Admin and mesh | A member handed a venom session to a teammate or a team (/handoff): who, to whom, the repository and branch; never the note. |
handoff.accepted |
Admin and mesh | The recipient of a handoff accepted it (venom handoff accept) and took the session over. |
handoff.declined |
Admin and mesh | The recipient of a handoff declined it. |
key_rotation.due |
Admin and mesh | A provider key or API key reaches its rotation date within 14 days (the org's schedule or the key's own; once per key version). Names and last four characters only. |
key_rotation.overdue |
Admin and mesh | A provider key or API key is past its rotation date (once per key version). |
key_rotation.completed |
Admin and mesh | A rotated provider key's old key stopped serving after its grace period (or an admin retired it). Revoke it at the provider. |
model.retiring |
Admin and mesh | A model the org's gears, routing rows or allow lists use retires within the org's warning window (30 days by default) or is gone from its provider's list (once per model and date). |
price.changed |
Admin and mesh | The effective price of a model used in the last 30 days changed (a price table update, a custom price, a catalog sync): old and new price and the monthly impact at the last 30 days' use. |
credits.expiring |
Admin and mesh | Prepaid credits or a free quota on a provider key expire within 7 days with a balance left (once per credit and expiry). Key name and amounts only. |
sla.breach |
Admin and mesh | A customer's or route's service-level target (availability, p95 time to first token, error rate) is missed this month so far (once per target and month): the figures, the target and a link to the SLA page. |
sla.credit_drafted |
Admin and mesh | A finished month breached a customer's SLA and a service credit was drafted for its next invoice; an admin approves it first (once per target and month). |
tasks.issue.created |
Tasks | A Venom Tasks issue was created, by a person or an agent: identifier, title, team, state, priority, assignee and delegate. Never the description. |
tasks.issue.updated |
Tasks | A Venom Tasks issue changed: its state, assignee, delegate (and whether an agent holds a claim on it), priority, labels or text. Several changes within a minute arrive as one event with the issue as it is now. |
tasks.issue.deleted |
Tasks | A Venom Tasks issue was deleted: its id and identifier. |
tasks.comment.created |
Tasks | A comment was added to a Venom Tasks issue, by a person or an agent's progress report: the issue, the comment id and who wrote it. Never the comment's text. |
globe.note.created |
Notes | A note was created in the org vault of Venom Notes (never a personal vault's): its id, path and who wrote it. Never the note's text. |
globe.note.updated |
Notes | A note in the org vault changed (its text, path or properties). Edits within a minute, live typing included, arrive as one event. |
globe.note.deleted |
Notes | A note in the org vault was moved to the trash or deleted. |
experiments.guardrail_breached |
Experiments | A guardrail metric of a running experiment is worse than its tolerated regression (once per experiment and metric). |
experiments.decided |
Experiments | An experiment was decided: a variation shipped, a rollback or an iteration, by a person, an agent or the automatic guardrail rollback. |
errors.issue.created |
Incidents | A new error issue appeared in Venom Incidents (id, project, title, count and release; never the event itself). |
errors.issue.regressed |
Incidents | A resolved error issue happened again in Venom Incidents. |
errors.alert.fired |
Incidents | One of the org's error alert rules fired (rule, kind, issue, the numbers behind it, and the action). |
incidents.created |
Incidents | An incident was declared in Venom Incidents (number, title, severity, status, projects; never its notes). |
incidents.updated |
Incidents | An incident's status, severity, roles or title changed. |
incidents.resolved |
Incidents | An incident was resolved. |
forms.response.created |
Forms | A response was submitted to a published Venom Forms form: its id, the form and the time. The answers are included only when the form's "include answers" setting is on (they can be personal data). |
incidents.page |
Incidents | Someone is being paged: the page, its title, the escalation level and the members told (so an org can bridge SMS or voice through its own gateway). Sent again at each escalation. |
comms.message.received |
Comms | Someone wrote to one of the org's numbers (Venom Comms): the channel, the sender, the conversation and the text, plus what it asked for (ack, escalate, STOP). |
support.conversation.created |
Support | A conversation was opened in Venom Support (email, a form, a messaging channel or by hand): its id, number, subject, channel and priority. Never the customer's message. |
support.sla.breached |
Support | An open Support conversation ran past its first-reply or resolution time: its id, number, which SLA (first_response or resolution), the due time and the priority. Never the customer's message. |
comms.message.status |
Comms | A message sent through Venom Comms changed status (sent, delivered, read, failed), with the provider's reason on a failure. |
comms.call.answered |
Comms | A call placed through Venom Comms was answered. |
comms.call.gather |
Comms | The person on a Venom Comms call pressed keys at a gather step: the step's name and the digits. |
comms.call.ended |
Comms | A Venom Comms call ended: its result, duration and cost. |
comms.call.status |
Comms | A Venom Comms call changed status (ringing, failed, busy, no answer). |
comms.dispatch.acknowledged |
Comms | Someone acknowledged a Venom Comms profile run (a reply of 1 or ack, or key 1 on the call): no further steps go out. |
calendar.booking.created |
Calendar | Someone booked a time on a Venom Calendar booking page (or the owner booked for them): the booking, event type, time, status (confirmed, or pending when it needs your confirmation), and the invitee's name, email and time zone. Never their answers. |
calendar.booking.confirmed |
Calendar | The owner confirmed a pending booking. |
calendar.booking.rescheduled |
Calendar | A booking moved to a new time, by the invitee from their link or by the owner: the new time, the previous one and the invite's sequence. |
calendar.booking.cancelled |
Calendar | A booking was cancelled by the invitee or the owner, or a pending one was declined: the reason given, if any. |
calendar.booking.no_show |
Calendar | The owner marked a booking as a no-show after its start: the booking, its time and the invitee (Funnel can move the deal back). |
tasks.issue.delegated |
Tasks | A Venom Tasks issue was delegated to an agent (at creation or later, each new delegate): the issue, its identifier and title, the delegate agent's id, the previous delegate and who delegated it, so an agent learns of new work without holding a stream open. Never the description. |
globe.team_note.created |
Notes | A note was created in a team vault of Venom Notes: its id, path, the ids of the teams whose vault holds it and who wrote it. Never the note's text, and never a personal vault's note. |
globe.team_note.updated |
Notes | A note in a team vault changed (its text, path or properties): id, path, team ids and who. Edits within a minute arrive as one event. |
globe.team_note.deleted |
Notes | A note in a team vault was moved to the trash or deleted: its id, path and team ids. |
experiments.started |
Experiments | An experiment started serving its treatments (by a person, an agent, or an approved request): the experiment, flag, environment, the treatments' share and who started it. |
experiments.ramped |
Experiments | A running experiment's treatment share changed (by hand, or a guarded rollout's next step): the share before and after, and who. |
experiments.stopped |
Experiments | A running experiment was stopped and control is served to everyone: the experiment, flag, environment and who stopped it. |
people.person.created |
People | A person became visible to the whole org in Venom People (added as org-wide, or shared with the org): id, name, role, company and the member who owns the record. Never handles, notes, how you met or interactions; a private or team-only person is never sent. |
people.person.updated |
People | An org-wide person in Venom People changed: the same short fields as when it was added. |
people.person.removed |
People | An org-wide person is no longer visible to the org: archived, merged into another, or made private or team-only again. Its id only. |
funnel.deal.created |
Funnel | A deal visible to the whole org was created in Venom Funnel: id, title, value, currency, pipeline, stage, status, owner and company. Never its notes or the people on it; a team-only deal is never sent. |
funnel.deal.updated |
Funnel | An org-wide deal's own fields changed (title, value, owner, company, expected close), or a team deal was opened to the org: the deal as it is now. A deal moved from the org to a team sends its id and visibility only. |
funnel.deal.stage_changed |
Funnel | An org-wide deal moved to another stage: the stage before and after, its status (open, won or lost) as it is now, and who moved it. |
funnel.deal.archived |
Funnel | An org-wide deal was archived: its id and title. |
chat.channel.created |
Chat | A public channel was created in Venom Chat: id, name and who created it. Private channels and direct messages are never sent. |
chat.channel.archived |
Chat | A public channel was archived in Venom Chat (or restored: archived false): id, name and who. |
chat.message.created |
Chat | A message was posted in a public channel of Venom Chat, by a person, an agent or a feed: the message id, channel, thread, author and how it was posted. Never the text; private channels and direct messages are never sent. Busy: one event per message. |
flags.flag.created |
Flags | A feature flag was created in Venom Flags: project, key, name, kind, version, who, and the audit entry. |
flags.flag.updated |
Flags | A feature flag changed (turned on or off, targeting, rollout, variations, archived, or reverted): project, key, version, the environment, whether it is on in each environment, the paths that changed (never their values, which can name users) and who. |
flags.flag.deleted |
Flags | A feature flag was deleted: project, key and who. |
org.team.created |
Org | A team was created in the organisation (shared by Tasks, Chat, Notes and People): id, key, name, parent, whether it is private, and who. |
org.team.updated |
Org | A team's name, key, parent, privacy or description changed: the team as it is now, and who. |
org.team.archived |
Org | A team was archived (or restored: archived false), and who did it. |
org.team.member_added |
Org | A person or agent joined a team: the team, the member's id, their role in it, and who added them. |
org.team.member_removed |
Org | A person or agent left a team: the team, the member's id and who removed them. |
status.incident.created |
Status page | An incident was published on the org's public status page: its title, impact, status, components and first update, as visitors see them. |
status.incident.updated |
Status page | A published status page incident got an update: its status and the update as posted on the page. |
status.incident.resolved |
Status page | A published status page incident was resolved. |
status.maintenance.scheduled |
Status page | A maintenance window was published on the status page: its title, times and components. |
status.maintenance.started |
Status page | A published maintenance window began. |
status.maintenance.completed |
Status page | A published maintenance window ended. |
status.component.changed |
Status page | A status page component (a model) went down or degraded, or is working again, as its automatic incidents see it: the component, its label, the new status (down, degraded, operational, or idle when it had no traffic) and the incident. |
Other ways to follow changes
- The change feed.
workspace_change_list(GET /api/v1/changes) answers what changed in notes and issues since your cursor. Pull it on your own schedule; no endpoint needed. - MCP resource subscriptions. A connected MCP client can subscribe to a note or an issue and be told as it changes (Venom for agents).
- Product webhooks. Flags has webhooks of its own for flag changes, Forms sends each response to its destinations, and the Status page sends incident and maintenance updates to its readers' webhooks. Each product's page says what it has under "Events".
- Incoming webhooks. Slack, Linear, Jira and Stripe call Venom: see Incoming webhooks.