---
title: Incoming webhooks
description: 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.
section: cloud
order: 430
audience: [operator, builder]
sources: [services/nodejs-cloud/app/api/integrations, services/nodejs-cloud/app/api/billing/webhook/route.ts, services/nodejs-cloud/app/api/clerk/webhook/route.ts, services/nodejs-cloud/lib/integrations, services/nodejs-cloud/lib/billing, services/nodejs-cloud/lib/customers/invoices.ts, docs/cloud-mesh.md]
features: [cloud.api-integrations, cloud.api-billing]
---

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](/docs/cloud/api-admin-observability.md#webhooks)).

## Your org's webhooks {#org}

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 {#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 {#intake}

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 {#customer-stripe}

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 {#deployment}

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 {#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 {#related}

- [Venom Cloud APIs overview](/docs/cloud/api-overview.md) for every surface.
- [Knowledge and tools API](/docs/cloud/api-knowledge.md) for the intake runner's protocol (`/v1/intake/*`).
- [Venom Cloud](/docs/cloud.md) for connecting integrations in the console.
