Incoming webhooks
The webhook URLs Venom Cloud receives from Slack, Linear, Jira, Stripe and Clerk, how each is signed and what it answers, so you can connect and debug them.
Some services call Venom Cloud: your org's Slack app, Linear or Jira when an issue is handed to venom, your own Stripe account for the invoices you send your customers, and, on a deployment, the platform's Stripe and Clerk accounts. Each has its own URL and is checked with that sender's signature before anything in the body is read. None of them takes a Venom key.
The events Venom Cloud sends out (to your URL, signed by Venom) are org webhooks and alert webhooks, set up in the admin API's webhooks and alerts routes (Admin API: logs, audit and alerts).
Your org's webhooks
You get these URLs from the console when you connect an integration: Settings, Integrations (Slack) and
Integrations, Intake (Linear, Jira), or Customers, Invoices (Stripe). {id} is the integration's id and
{tenant} your org's id.
| Route | Sender | Signature | Answers |
|---|---|---|---|
POST /api/integrations/slack/{id}/events |
your Slack app's Events API | x-slack-signature: v0= + hex HMAC-SHA256 of v0:<timestamp>:<body> with the app's signing secret; x-slack-request-timestamp within 5 minutes |
the challenge for url_verification; 200 for every signed event (deduplicated on event_id) |
POST /api/integrations/slack/{id}/commands |
your Slack app's /venom slash command |
as above | an ephemeral reply at once; the answer follows in the channel |
POST /api/integrations/linear/{id}/webhook |
your Linear workspace | Linear-Signature: hex HMAC-SHA256 of the raw body with the webhook's secret; webhookTimestamp at most 60 seconds old |
200 once verified |
POST /api/integrations/jira/{id}/webhook |
your Jira Cloud site | X-Hub-Signature: sha256=<hex> with the webhook's secret |
200 once verified |
POST /api/integrations/stripe/{tenant}/webhook |
your own Stripe account | Stripe-Signature with your account's signing secret |
200 once verified; 404 when the org has not connected Stripe |
All of them answer 404 for an unknown id, 401 (Slack, Linear, Jira) or 400 (Stripe) for a missing,
wrong or stale signature, and 413 for a body over 1 MiB (512 KiB for Stripe).
Slack
The Events URL takes app_mention in channels and message.im in direct messages, and answers them with the
gear the channel is set to. The /venom command takes /venom <question>, /venom ask <question> (answered
from the org's memory, library and session summaries, with sources), /venom link, /venom gear [name|default]
and /venom help. Slack needs an answer within 3 seconds, so both routes check
the signature, record the event and acknowledge at once; the answer runs after the response. A paused
integration acknowledges and does nothing. Which channels answer is the integration's setting (channels:
any, or listed for channels with a gear) and allow_dms.
Linear and Jira
An issue handed to venom becomes a job for a runner your org controls (venom intake run), which opens a pull
request and reports back; the cloud then comments on the issue.
| Linear | Jira | |
|---|---|---|
| Starts a job | an issue created with the trigger label, an update that adds the label, or an assignment to the configured assignee | jira:issue_created with the label or assignee, or jira:issue_updated whose changelog adds the label or the assignee |
| Redelivery dedup | Linear-Delivery |
X-Atlassian-Webhook-Identifier |
The trigger label defaults to venom. Once the signature checks out the answer is always 200, so the tracker
never retries a delivery Venom has seen: a duplicate, an event from a pending or paused integration, or an event
that does not hand an issue to venom is acknowledged with {"ok": true, "ignored": "…"}. An issue has at most
one live job.
Stripe, for your customer invoices
When you resell Venom to your own customers and connect your Stripe account, Stripe tells Venom what happened to
the invoices it sent. invoice.paid and invoice.payment_succeeded mark the invoice paid, invoice.voided
voids it, invoice.payment_failed records the failure, and invoice.finalized, invoice.sent,
invoice.updated, invoice.overdue and invoice.marked_uncollectible update its status and hosted link. Other
events are ignored.
Add the endpoint in your Stripe dashboard (Developers, Webhooks) with those invoice.* events, and paste its
signing secret in the console.
Deployment webhooks
Only an operator running their own deployment sets these up, with the platform's own Stripe and Clerk accounts.
| Route | Sender | Signature | Needs |
|---|---|---|---|
POST /api/billing/webhook |
the platform's Stripe account (plans and seats) | Stripe-Signature, 5-minute tolerance |
STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET, else 503 webhook_not_configured |
POST /api/clerk/webhook |
Clerk (organisations and memberships) | Svix signature, 5-minute tolerance | CLERK_WEBHOOK_SIGNING_SECRET, else 503 |
The billing webhook applies checkout.session.completed (a subscription checkout), customer.subscription.created,
customer.subscription.updated, customer.subscription.deleted and invoice.payment_failed to the org's plan.
Each event id is recorded in the same transaction, so Stripe's redeliveries answer 200 with
"result": "duplicate". A failure answers 500 without recording the event, so Stripe retries it. Other
answers: 400 bad_signature, 400 invalid_json, 413 too_large (over 512 KiB).
The Clerk webhook applies organization.* and organizationMembership.* events idempotently. A Clerk role
change never overrides a member's Venom role; organization.deleted removes the members and revokes the org's
keys and join tokens.
Troubleshooting
| Symptom | Cause |
|---|---|
404 on every delivery |
the integration was deleted or the URL has the wrong id; copy it again from the console |
401 from Slack |
the signing secret in the console is not the app's, or the server clock and Slack's differ by more than 5 minutes |
401 from Linear |
the webhook secret differs, or the delivery is older than 60 seconds (a delayed retry) |
200 with ignored |
the integration is paused or pending, the delivery is a duplicate, or the event does not hand the issue to venom (check the trigger label and assignee) |
Stripe shows 400 bad_signature |
the endpoint's signing secret in the console (or in STRIPE_WEBHOOK_SECRET) is not this endpoint's |
Related
- Venom Cloud APIs overview for every surface.
- Knowledge and tools API for the intake runner's protocol (
/v1/intake/*). - Venom Cloud for connecting integrations in the console.