Webhooks
Webhooks Getting Started
Learn how to create reliable webhook integrations with the OMX Webhook API.
Webhooks
Build with confidence
Webhooks enable real-time communication between OMX and your applications. Get instant notifications about events, trigger custom logic, and build event-driven architectures with guaranteed delivery.
Installation & Setup
Get started with webhook integrations in just a few steps.
1
Install the packages
Install Core SDK and Webhook module
typescript
1# npm
2npm install @omx-sdk/core @omx-sdk/webhook
3
4# yarn
5yarn add @omx-sdk/core @omx-sdk/webhook
6
7# pnpm
8pnpm add @omx-sdk/core @omx-sdk/webhook
2
Initialize the Webhook module
Set up your OMX client and Webhook module
typescript
1import { OMXClient } from '@omx-sdk/core';
2import { Webhook } from '@omx-sdk/webhook';
3
4const omx = new OMXClient({
5 clientId: 'your_client_id',
6 secretKey: 'your_secret_key'
7});
8
9const webhook = new Webhook(omx);
3
Create your first webhook
Set up a webhook endpoint to receive events
typescript
1const webhookEndpoint = await webhook.create({
2 url: 'https://your-app.com/webhooks/omx',
3 events: ['geotrigger.entered', 'email.delivered'],
4 secret: 'your-webhook-secret'
5});
6
7console.log('Webhook created:', webhookEndpoint.id);
Webhook Features
Powerful event-driven capabilities for real-time integrations.
Real-time Events
Instant notifications when events occur in your OMX applications.
Secure Delivery
HMAC signature verification and HTTPS-only delivery for security.
Retry Logic
Automatic retry with exponential backoff for failed deliveries.
Event Filtering
Subscribe to specific events and filter by custom criteria.
Creating a Webhook Endpoint
Set up a webhook with event filtering and retry configuration.
typescript
1const webhookEndpoint = await webhook.create({
2 url: 'https://your-app.com/webhooks/omx',
3 events: [
4 'geotrigger.entered',
5 'geotrigger.exited',
6 'email.delivered',
7 'push.delivered'
8 ],
9
10 // Security settings
11 secret: 'your-webhook-secret',
12
13 // Retry configuration
14 retryPolicy: {
15 maxRetries: 3,
16 backoffMultiplier: 2,
17 initialDelay: 1000 // ms
18 }
19});
20
21console.log('Webhook created:', webhookEndpoint.id);
Handling Webhook Events
Set up your endpoint to receive and process webhook events securely.
typescript
1// Express.js example
2app.post('/webhooks/omx', express.json(), (req, res) => {
3 const event = req.body;
4 const signature = req.headers['omx-signature'];
5
6 // Verify webhook signature
7 if (!webhook.verifySignature(req.body, signature, 'your-webhook-secret')) {
8 return res.status(400).send('Invalid signature');
9 }
10
11 // Process the event
12 switch (event.type) {
13 case 'geotrigger.entered':
14 handleGeotriggerEntered(event.data);
15 break;
16 case 'email.delivered':
17 handleEmailDelivered(event.data);
18 break;
19 default:
20 console.log('Unhandled event type:', event.type);
21 }
22
23 res.status(200).send('OK');
24});
Geotrigger Events
Real-time location-based event notifications with detailed context.
typescript
1{
2 "type": "geotrigger.entered",
3 "data": {
4 "triggerId": "gt_12345",
5 "userId": "user_67890",
6 "location": {
7 "lat": 40.7128,
8 "lng": -74.0060
9 },
10 "timestamp": "2024-01-15T10:30:00Z"
11 }
12}
Email Events
Track email delivery status and engagement metrics.
typescript
1{
2 "type": "email.delivered",
3 "data": {
4 "messageId": "msg_12345",
5 "recipient": "user@example.com",
6 "subject": "Welcome!",
7 "timestamp": "2024-01-15T10:35:00Z"
8 }
9}
Security Best Practice: Always verify webhook signatures to ensure requests are authentic and from OMX.
Webhook Security
Implement signature verification and additional security measures.
typescript
1// Verify webhook signatures
2function verifyWebhookSignature(payload, signature, secret) {
3 const crypto = require('crypto');
4 const expectedSignature = crypto
5 .createHmac('sha256', secret)
6 .update(JSON.stringify(payload))
7 .digest('hex');
8
9 return signature === `sha256=${expectedSignature}`;
10}
11
12// IP whitelist (optional)
13const allowedIPs = [
14 '52.95.216.0/24',
15 '52.95.217.0/24'
16];
17
18// Middleware for IP validation
19function validateIP(req, res, next) {
20 const clientIP = req.ip;
21 if (allowedIPs.some(range => isIPInRange(clientIP, range))) {
22 next();
23 } else {
24 res.status(403).send('Forbidden');
25 }
26}
Advanced Event Processing
Build robust event handlers with error handling and logging.
typescript
1async function handleGeotriggerEntered(data) {
2 try {
3 // Log the event
4 console.log(`User ${data.userId} entered trigger ${data.triggerId}`);
5
6 // Send personalized notification
7 await sendLocationNotification(data.userId, data.triggerId);
8
9 // Update user analytics
10 await updateUserLocationAnalytics(data.userId, data.location);
11
12 // Trigger downstream actions
13 await triggerLocationBasedActions(data);
14
15 } catch (error) {
16 console.error('Error processing geotrigger event:', error);
17 // Implement error recovery or alerting
18 }
19}
20
21async function handleEmailDelivered(data) {
22 try {
23 // Update delivery status
24 await updateEmailStatus(data.messageId, 'delivered');
25
26 // Update user engagement metrics
27 await updateUserEngagement(data.recipient, 'email_delivered');
28
29 // Trigger follow-up actions
30 await scheduleFollowUpEmail(data.recipient);
31
32 } catch (error) {
33 console.error('Error processing email event:', error);
34 }
35}
Next Steps
Explore advanced webhook features and build sophisticated event-driven workflows.
Advanced Webhook Creation
Complex webhook configurations and filtering
Complete Event Reference
All available webhook event types
Security Best Practices
Secure webhook implementation patterns
Event Processing Patterns
Common webhook processing architectures
Geotriggers
Location-based automation triggers
Email API
Email delivery and tracking