Webhooks

Deliver Selwise events to custom HTTP destinations with auth, retry, and delivery logging controls.

Audience: Backend and integration teams consuming Selwise events in external systems.

Critical: Webhook routes are dedicated under /api/v1/sites/:siteId/integrations/webhooks and are not provider aliases.

Integrations Overview Operations Errors and Retries

Who This Page Is For

Use this page when you need to push Selwise events into internal platforms, CDPs, or custom automation systems.

Quick Start (2-5 Minutes)

Create webhook endpoint

Define destination URL, events, auth, and retry policy.

POST /api/v1/sites/:siteId/integrations/webhooks

List and verify

Review active webhooks and their settings.

GET /api/v1/sites/:siteId/integrations/webhooks

Run webhook test

Send test payload to endpoint before production use.

POST /api/v1/sites/:siteId/integrations/webhooks/:webhookId/test

Inspect delivery logs

Review status, failures, and retries.

GET /api/v1/sites/:siteId/integrations/webhooks/:webhookId/logs?limit=50

Update or disable

Patch destination/auth/events or deactivate webhook.

PUT /api/v1/sites/:siteId/integrations/webhooks/:webhookId

Webhook endpoints

GET    /api/v1/sites/:siteId/integrations/webhooks
POST   /api/v1/sites/:siteId/integrations/webhooks
GET    /api/v1/sites/:siteId/integrations/webhooks/:webhookId
PUT    /api/v1/sites/:siteId/integrations/webhooks/:webhookId
DELETE /api/v1/sites/:siteId/integrations/webhooks/:webhookId
POST   /api/v1/sites/:siteId/integrations/webhooks/:webhookId/test
GET    /api/v1/sites/:siteId/integrations/webhooks/:webhookId/logs

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`name`	Required	`string`	Create webhook	Operational identifier for webhook.
`url`	Required	`URL`	Create/update webhook	Destination endpoint for deliveries.
`events`	Optional	`string[]`	Create/update webhook	Subscribed event names.
`authType and authConfig`	Optional	`none \| bearer \| basic \| hmac \| signature \| api_key`	Create/update webhook	Authentication strategy and credentials.
`retryPolicy`	Optional	`{maxAttempts,initialDelay,backoffMultiplier}`	Create/update webhook	Retry strategy tuning.
`isActive`	Optional	`boolean`	Create/update webhook	Enable/disable webhook without deleting configuration.

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Add new downstream consumer	POST /integrations/webhooks	Creates isolated webhook config per consumer.
Validate receiver readiness	POST /integrations/webhooks/:webhookId/test	Pre-launch delivery validation.
Investigate failures	GET /integrations/webhooks/:webhookId/logs	Visibility into statuses and retries.
Temporarily stop deliveries	PUT ... isActive=false	Safe pause without config loss.
Permanently retire endpoint	DELETE webhook	Removes obsolete integration route.

Common Errors and Fixes

Webhook test fails with authentication error

Cause: authType/authConfig mismatch with receiver expectations.

Fix: Align auth method and secret/header values with receiver contract.

Deliveries retry repeatedly

Cause: Receiver endpoint unstable or returns non-2xx responses.

Fix: Stabilize receiver and tune retry policy as needed.

No deliveries observed

Cause: isActive false or event subscription list excludes actual events.

Fix: Enable webhook and include relevant event types.

Security concern around destination URLs

Cause: Potential internal/private destination attempts.

Fix: Use approved public endpoints and adhere to webhook URL restrictions.

Production Checklist

Webhook auth and retry policy are defined explicitly.Required
Test endpoint passes before production enablement.Required
Delivery logs are monitored for non-2xx patterns.Required
Inactive webhooks are reviewed and cleaned periodically.Required
Receiver SLA and backoff behavior are aligned with retry policy.Required