Skip to content
Docs menu

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.

View .md

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