Webhook Issues¶

Outcome: Diagnose a webhook that isn't accepting requests, and rotate a leaked secret safely. Audience: Everyone / Developers · Tags: troubleshooting, webhook, secret

The webhook URL is /api/v1/webhooks/<flowId>/<secret>. The secret in the path is the entire authorization scheme — there's no separate signature or header to configure. That makes the secret worth protecting like a password, and makes "wrong secret" the most common webhook failure.

Symptoms → cause → fix¶

The request is rejected outright (wrong secret or unknown flow)¶

An unrecognized flow ID or an incorrect secret both come back the same way: a 404 with no further detail. This is deliberate — SnapLink won't tell an attacker whether a given flow ID even exists, so "bad secret" and "no such flow" are indistinguishable from the outside. In practice, treat any 404 here as: this exact URL isn't valid right now.

Fix: Get a fresh, correct copy of the URL from the flow — GET /flows/:id/webhook (or the flow's page in the app) — rather than retyping or reusing an old one. If the secret was recently rotated, the old URL is expected to stop working eventually (see below).

The request body is too large¶

Webhook request bodies are capped at 1 MB. A larger payload is rejected before it reaches the flow. Fix: send a smaller payload — SnapLink webhooks are meant to carry an event notification, not a bulk data dump; do the heavy lifting on the sending side and pass SnapLink what it needs to react.

You're not sure the webhook actually fired¶

Webhook request metadata (method, content type, size, accept/reject outcome) is recorded even for rejected calls — but the request body is never stored, so you can't replay it or inspect its contents after the fact.

Fix: Check recent runs for the flow:

curl -s "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/runs?workspaceId=$WS&flowId=$FLOW_ID" \
  -H "Authorization: Bearer $TOKEN"

If a run with a matching timestamp exists, the webhook fired and SnapLink accepted it — from there, any problem is an execution problem, not a webhook problem; see Connector failed or Execution failures. If no run exists for that time, the request was rejected (wrong secret, inactive flow, or rate limited) — see Flow not running.

You're getting `429`¶

Ingress is rate-limited per IP, per flow endpoint, and per workspace. See Rate limiting.

Rotating a leaked secret safely¶

If a webhook URL leaked (committed to a public repo, pasted somewhere it shouldn't have been, an ex-employee's integration, etc.), rotate it:

curl -s -X POST https://api.snaplink.cloudsolutionaccelerators.com/api/v1/flows/<flowId>/webhook/rotate \
  -H "Authorization: Bearer $TOKEN"

This issues a new secret immediately. The old secret keeps working for a grace window after rotation, specifically so you can update every sender without a gap in coverage — rotate, update your caller(s) to the new URL, confirm they're using it, and let the old one expire naturally rather than needing perfect timing. During the grace window, requests using either the old or the new secret are accepted.

Advanced diagnostics¶

The HTTP status your sender receives tells you what happened: 202 accepted (a run was created) · 404 unknown flow or bad/expired secret · 409 flow exists but isn't Active · 429 rate limited.
The response body on success is intentionally minimal — { "ok": true, "data": { "runId": "...", "status": "queued" } } — the inbound payload is never echoed back.

When to contact support¶

You have the current, correct URL, you're inside the grace window if you recently rotated, and you're still getting 404s. Include the flow name, the approximate time of the request, and whether you're calling through a proxy or gateway that might be rewriting the URL.

Related: Flow not running · Rate limiting · Security

Was this helpful? 👍 👎