Troubleshooting.

The event didn't reach Hooktopus at all

Check the source's webhook delivery log — Stripe, Shopify, GitHub all have one. If the source shows 200/202, we received it. If it shows a 4xx or 5xx, we either rejected it or didn't see it.

• 401: the endpoint requires HMAC and the signature didn't verify. Re-check the signing secret.
• 404: the URL is wrong. Workspace ID or endpoint name is off. The URL is case-sensitive.
• 429: you hit the per-endpoint rate limit (default 10 req/s). Bump it in endpoint settings.

The event arrived but didn't reach BigQuery

Visit /w/[slug]/inspector — events appear there within ~1 second of ingestion, before any destination writes happen. If you see it in the inspector but not BQ, the issue is downstream.

Common BigQuery write failures

• Permission denied: the SA lost dataEditor on the dataset. Re-grant per /docs/bigquery-setup.
• Table not found: someone deleted the events table. Hooktopus does not recreate it automatically — re-run step 4 of the BQ setup doc.
• Quota exceeded: BQ streaming inserts have a default quota of 1M rows/second per table. You'd need to be at unicorn scale to hit it. If you are, email us.

The destination shows "Error"

/w/[slug]/destinations shows a status badge per destination. Errors persist the most recent BQ failure message in the last_error column. Common patterns:

# Permissions issue (most common)
last_error: "googleapi: Error 403: Access Denied: Dataset hooktopus-prod:raw"

# Credentials expired (rare; SA keys don't expire by default)
last_error: "googleapi: Error 401: invalid_grant"

# Project deleted
last_error: "googleapi: Error 404: Not found: Project hooktopus-old"

Inspector shows the event but the timestamp looks wrong

received_at is when Hooktopus's ingress Worker received the request. Workers run at the Cloudflare edge nearest the source, so the timestamp is very close to "wall-clock time the source sent it." If you're seeing minutes of skew, it usually means the source is retrying — check the source's webhook log for a chain of attempts.

I sent a test event with curl and it 202'd but I don't see it

Things to check, in order:

1. Workspace ID in the URL exactly matches the one in the hub URL.
2. Endpoint name in the URL exactly matches what you created in the hub.
3. The endpoint is enabled (toggle in endpoint settings).
4. A destination is attached to that endpoint and shows Active.
5. The destination's BQ table exists and the SA still has permissions.

If all five check out and the event still isn't there, email hi@hooktopus.io with your event ID (from the 202 response). We can trace it through the queue and tell you exactly where it died.

The dbt-generated SQL won't compile

Almost always: your dbt project's sources block points at a different database/schema than what we wrote in _hooktopus__sources.yml. Edit the YAML to match your dbt project's conventions — it's just config, not a generated artifact.

Less common: you're on a dbt version <1.6 and don't have json_value in your adapter's dispatch table. Upgrade dbt; we target 1.6+.

Schema drift alert keeps firing for the same field

By default, an alert fires once when a new field is detected and never again for that exact path. If you regenerated your dbt model, the field is now "known" — re-firing means a) the regeneration didn't include this field (check your % threshold), or b) the field type changed too. Both are addressable by editing the field-include settings in /w/[slug]/alerts-config.

Still stuck?

Email hi@hooktopus.io with:

• Workspace ID
• Endpoint name (or destination ID, depending on layer)
• A sample event ID, if you have one
• Timestamp window when the problem occurred

We typically reply within a business day. SLAs differ by plan.