Catch Troubleshooting

Signature verification failing

Q: I get catch.signature_invalid. How do I fix it?

  • Wrong signing secret. Stripe secrets start with whsec_. GitHub secrets must match exactly. Shopify secrets are base64 encoded.
  • Header mismatch. Verify the provider sends the expected header (stripe-signature, x-hub-signature-256, x-shopify-hmac-sha256, or svix-signature).
  • Body modified in transit. Proxies or middleware that alter the request body break signatures.
  • Stale timestamp. Some providers reject signatures older than a few minutes.

Diagnose by checking your bucket config with GET /v1/catch/buckets/{bucket_id}.

Duplicate events

Q: The same event appears multiple times with is_replay: true.

  • Normal when providers retry failed deliveries. Catch marks duplicates with is_replay: true.
  • Return 200 immediately to prevent retries.
  • Use the original event ID for idempotency in your processing logic.

Webhooks not appearing in bucket

Q: Provider shows successful delivery but my bucket has zero events.

  • Verify the bucket exists and check its state.
  • Confirm the webhook URL: https://api.solenoid.systems/v1/catch/{bucket_id}.
  • Temporarily remove the signing secret to rule out silent signature rejection.

Provider not recognized

Q: I get catch.provider_unsupported.

  • Catch supports Stripe, GitHub, Shopify, and Svix.
  • Set the provider explicitly when creating the bucket.
  • For unsupported providers, use Svix as a webhook proxy.

Replay not reaching endpoint

Q: I get catch.replay_failed or my endpoint never receives the event.

  • Verify target_url is publicly accessible and accepts POST with JSON body.
  • Check endpoint logs for non-2xx responses.
  • Whitelist Catch’s IP ranges if you use a firewall.
  • As a fallback, retrieve the payload directly with GET /v1/catch/buckets/{bucket_id}/events/{event_id}.

Events missing from bucket

Q: Events I captured earlier have disappeared.

  • Events expire based on tier retention (Free: 24h, Starter: 3d, Pro: 30d, Scale: 90d).
  • Per-bucket event limits apply. Oldest events are deleted when the limit is reached.
  • Verify you are querying the correct bucket ID.

Bucket not found

Q: I get catch.bucket_not_found on a bucket that worked before.

  • Bucket IDs are case-sensitive. Verify the exact ID.
  • The bucket may have been deleted. List buckets with GET /v1/catch/buckets.
  • Confirm you are using the correct API key (buckets are scoped to the key’s owner).