Configure webhooks
Prepare the callback, subscription rules, auth, and signature verification details needed for an OmniLab webhook setup.
Use this article to prepare a webhook implementation with OmniLab. The actual callback and subscription records are configured with OmniLab teams today, but you can prepare your endpoint, authentication, filters, and verification logic in advance.
Prerequisites
- A public HTTPS endpoint that can receive OmniLab requests
- Server-side secret storage for signing secrets and callback credentials
- Separate staging and production receivers
- A clear list of the event types and filters you need
Prepare the setup
Decide what each callback is responsible for
Prefer one callback per downstream responsibility. For example, use one callback for CRM sync and another for analytics export instead of sending every event to one large receiver.
Choose the authentication model
Pick the simplest model your downstream service accepts:
| Auth mode | Good fit |
|---|---|
| None | Receiver is already protected another way and only needs signature verification |
| Basic | Legacy endpoints that already use username and password |
| Bearer | Downstream services that expect a static API token |
| OAuth 2.0 client credentials | Platforms that issue short-lived access tokens |
Define the subscriptions
Each subscription links one callback to one or more event types, then narrows delivery with optional filters.
{
"subscription_name": "Reward wins for summer campaign",
"callback": "reward-win-receiver",
"event_category_types": ["reward.won.v1", "reward.redeemed.v1"],
"filters": [
"tenant_id=<tenant-id>",
"interaction_id=<interaction-id>"
]
}Use tenant_id when the receiver should see the whole tenant feed, group_id when the feed should be narrowed to one organisation or group, and interaction_id when you need one campaign-specific stream.
Implement signature verification and idempotency
Verify the webhook-signature header against the raw body before doing any work. Then store the webhook-id so retries or duplicate deliveries do not repeat downstream side effects.
Test retries and secret rotation in staging
Before go-live, simulate success, 429, 5xx, and 410 Gone responses. Rotate the signing secret and confirm your verifier accepts both the current and previous signature during the rollout window.
Optional request transformation
OmniLab can optionally transform callback requests by changing:
- the HTTP method
- the content type
- the request body
- the destination URL
- custom headers
These transformations are rendered with Liquid and can reference the outbound event object.
{
"eventId": "{{ event.id }}",
"eventType": "{{ event.type }}",
"rewardId": "{{ event.payload.reward_id }}"
}OmniLab reserves its own signature and auth headers, so custom headers should be used only for your own downstream requirements.
Receiver checklist
- Return a
2xxresponse quickly once the request is accepted. - Move heavy downstream work onto an async queue or worker.
- Log
webhook-id, event type, and status code for debugging. - Keep staging and production callback URLs, credentials, and secrets separate.
- Make the receiver idempotent before production traffic starts.