Skip to main content

Webhooks overview

The Webhook Service delivers event messages from your app to external systems. Use it when your backend, automation tool, data pipeline, or support workflow needs to react to Switera activity.

Switera webhooks page with overview, endpoints, deliveries, event catalog, and test send tabs
A new app can start without webhooks. Add an endpoint when an external system needs event data.

Core objects​

ObjectMeaning
EndpointHTTPS destination that receives webhook messages.
Event typeThe event name an endpoint can subscribe to.
Event catalogThe list of built-in and builder-defined events for the app.
DeliveryA message sent to an endpoint.
AttemptA specific HTTP attempt for a delivery.
Endpoint secretSecret used by your receiver to verify message authenticity.

First webhook setup​

Select Add Webhook or Add first endpoint, then enter the receiver details.

Switera webhook endpoint form with sample HTTPS receiver URL
Start with one HTTPS endpoint and a small event set. Expand only after the receiver handles test traffic correctly.
  1. Open Services > Webhooks.
  2. Select Add Webhook.
  3. Enter an HTTPS receiver URL.
  4. Choose the event types your receiver understands.
  5. Save.
  6. Copy and store the endpoint secret securely.
  7. Send a test event.
  8. Confirm the receiver validates and processes the message.

Generate integration recipes​

The Webhooks overview includes an Integration recipes panel for receiver and backend emit code. Use it when creating the endpoint, or after selecting an existing endpoint.

The panel generates:

  • .env.example entries for the receiver secret, receiver path, app ID, base URL, and trusted backend API key
  • a receiver route that verifies signatures from the raw request body
  • a trusted backend custom-event emit call to /api/v1/apps/{appId}/webhooks/emit

Supported launch stacks are Express API, Next.js route handlers, SvelteKit endpoints, Go HTTP handlers, and Python Flask. Receiver secrets and app API keys are server-side only. Do not expose them to browser code.

Event classes​

Switera can expose several event families:

  • app and organization lifecycle events
  • Auth events
  • email service events
  • webhook delivery events
  • builder-defined events emitted by your backend through the Switera API

Only subscribe to events your receiver actually uses.

Health states​

StateMeaning
SetupEndpoint exists but has no meaningful delivery history yet.
ReadyEndpoint is configured and ready for test or real traffic.
LiveEndpoint has successful delivery activity.
AttentionRecent delivery failures or pending retries need review.

Good webhook design​

  • Use HTTPS endpoints.
  • Validate signatures.
  • Respond quickly with a success status.
  • Process slow work asynchronously in your system.
  • Make event handling idempotent.
  • Store delivery IDs for diagnosis.
  • Retry from Switera only after fixing the receiver.

Related pages: