Endpoints

An endpoint is a unique ingress point where CatchHook receives events on your behalf. Endpoints come in two kinds:

• Webhook — a URL that receives HTTP requests (POST, GET, PUT, etc.)
• Email — a generated email address that receives inbound emails

Both kinds store incoming events so you can inspect, forward, and alert on them.

Creating an endpoint

1. Go to Endpoints in the sidebar.
2. Click New Endpoint.
3. Choose the Kind: Webhook or Email.
4. Fill in the fields:
   • Name (required) — a human-readable label, e.g., "GitHub Webhooks" or "Transactional Emails".
   • Note (optional) — free-text notes visible on the endpoint page.
   • Custom ID (Pro, webhook only) — set a memorable path segment like checkout instead of the auto-generated ID.
   • Email local part (email only) — customize the part before the @ in the generated email address (e.g., billing becomes billing@in.catchhook.app). If omitted, a random local part is generated.
   • Encryption (Pro) — encrypt the event body, headers, and source IP at rest.
   • Custom Response (webhook only) — configure the HTTP status code, content type, and body that callers receive (see below).
   • Provider (webhook only) — the expected webhook source (GitHub, Stripe, etc.) for signature verification setup.
   • Notify once — when enabled, alerts fire only on the first occurrence until acknowledged.
   • Team (Business) — assign the endpoint to a team for shared access.
5. Click Create Endpoint.

Endpoint URL formats

Webhook endpoints

Configure your namespace or subdomain in Account Settings.

Email endpoints

The email domain is always in.catchhook.app. Custom local parts must be lowercase alphanumeric with dots, hyphens, or underscores (2–50 characters).

Endpoint workspace

Each endpoint page is a health-first debugging workspace. Instead of tabs, it uses a single-page layout with:

• Health header — endpoint name, health state badge (Setup incomplete, Healthy, Needs attention, Idle, Expired), ingress address (webhook URL or email address) with copy button, and feature badges for configured capabilities.
• Quick-actions bar — one-click access to Send Test Request (webhook) or copy email address (email), a Notify Next Request toggle, and an expandable Note field. These are always visible without scrolling.
• Recommended action — when the endpoint needs attention, a single action banner appears (e.g., "Active alerts firing — View alerts", "No events yet — Copy URL").
• Status cards — a 2x3 grid showing receive, verify, forward, tunnel, replay, and alert status at a glance.
• Recent failures — only shown when there are recent errors (failed forwards, signature failures, etc.).
• Recent activity — the last 5 events in an accordion view with inline delivery events (forwards, tunnels, replays) per event. Streams in real time via Turbo.

Configuration panels

Below the activity section, collapsible panels provide access to configuration:

Panels auto-open when they need attention (e.g., alerts panel opens when there are active alert instances).

Custom responses (webhook only)

By default, CatchHook responds with 200 OK (empty body) when a webhook arrives. You can override this to simulate different server behaviors — useful for testing retry logic, error handling, or validating that a webhook provider accepts your expected response.

Configure custom responses in the Custom Response section when creating or editing a webhook endpoint:

Webhooks are always captured and stored regardless of the response code — the custom response only affects what the sender sees.

Status codes that cannot carry a body (204, 304) will always return an empty response even if a body is configured.

Every webhook request records the response that was actually returned to the sender (status code, content type, body, and whether it was a default or custom response). This means you have a per-request audit trail even if the endpoint's response configuration changes over time. See Response capture for details.

Custom responses are available on all plans including trials. Not applicable to email endpoints — email delivery is managed by AWS SES and returns standard SMTP responses.

Signature verification (webhook only)

CatchHook can verify webhook signatures for known providers. Configure signing secrets in the endpoint's Signature Verification tab:

When configured, each incoming request shows a verification badge:

• Verified — signature matches.
• Failed — signature present but invalid.
• Missing — expected signature header not found.
• Not configured — no signing secret set up.

Requests are always stored even if verification fails. This lets you debug delivery issues safely.

Signature verification is not applicable to email endpoints. Email authentication (SPF, DKIM, DMARC) is handled by AWS SES at the transport level and displayed on the email event detail page.

Email authentication

For email endpoints, CatchHook displays the authentication results provided by AWS SES for each inbound email:

Results are shown as PASS or FAIL on each email event's detail page.

Provider detection

CatchHook automatically detects the source of incoming events and extracts structured data.

Webhook providers

Detection works through headers (e.g., X-GitHub-Event, Stripe-Signature) and, for some providers, body content.

Detected providers: GitHub, Stripe, Shopify, Slack, Twilio.

Slack provider mode covers requests sent from Slack to the endpoint through the Events API, slash commands, and interactivity. It is separate from Slack incoming-webhook message URLs and CatchHook's outgoing Slack App.

When a provider is detected, you'll see:

• A provider badge on each event in the dashboard (e.g., "GitHub push", "Stripe invoice.paid").
• Provider context in the event detail view showing extracted fields like delivery ID, actor, livemode, and shop domain.
• Replay warnings when replaying events that could have side effects (e.g., "Replaying workflow_run may retrigger CI pipelines").

Provider detection happens automatically at ingest time regardless of whether the endpoint has a provider set. Setting a provider on the endpoint (via CLI --provider flag or API) additionally enables signature verification setup.

Email providers

For email endpoints, CatchHook detects the originating email service from headers:

Detected providers: Amazon SES, Google/Gmail, Microsoft/Outlook, SendGrid, Postmark, Mailgun.

The detected provider is shown on the email event detail page and included in the normalized payload.

Archiving

Archive an endpoint to hide it from the main list without deleting it or its data. Archived endpoints:

• Stop appearing in the default endpoint list (use the "Archived" filter to view them).
• Continue receiving events normally.
• Can be unarchived at any time.

Sending a test request (webhook only)

Click Send Test Request in the quick-actions bar on any webhook endpoint to fire a sample POST with a JSON body. This is useful for verifying your endpoint URL works before configuring it in an external service.

For email endpoints, send a test email to the displayed address from any email client.

Deleting an endpoint

Open the Danger Zone panel at the bottom of the endpoint page and click Delete. This permanently removes the endpoint and all of its stored events, actions, and alerts.

Rate limits

Incoming webhook requests are subject to per-endpoint and per-account rate limits based on your plan. When a limit is exceeded, senders receive a 429 Too Many Requests response with a Retry-After header.

Temporary endpoints are limited to 50 requests per hour.

See Billing & Plans for the full rate limit table.

Plan limits