Skip to content
Docs menu

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.

View .md

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" } }
  • id is the event's id: the same on every retry of it, so use it to drop duplicates.
  • data carries 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.
  • links points 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.updated a 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.