Webhooks

Learn how to configure webhooks to receive real-time notifications when events occur in your Optare organization.

What are Webhooks?

Webhooks allow your application to receive HTTP callbacks when specific events happen, such as:

• New member joins organization
• Subscription changes
• OAuth client created
• Product access granted
• User profile updated

Instead of polling for changes, events are pushed to your server instantly.

Viewing Webhooks

1. Go to Settings → Webhooks
2. See all configured webhooks:
   • Endpoint URL
   • Events subscribed to
   • Status (Active/Inactive)
   • Last delivery timestamp

Creating a Webhook

Step 1: Create Endpoint

1. Go to Settings → Webhooks
2. Click "Create Webhook" or "New Webhook"

Step 2: Configure

• Webhook URL: Your server endpoint (must be HTTPS)
  • Example: https://api.yourapp.com/webhooks/optare
• Description: Optional note about this webhook
• Secret: Auto-generated for signature verification

Step 3: Select Events

Choose which events to receive:

Organization Events

• organization.updated - Org details changed
• organization.member.added - New member joined
• organization.member.removed - Member left
• organization.member.role_changed - Role updated

Subscription Events

• subscription.created - New subscription
• subscription.updated - Changes to subscription
• subscription.cancelled - Subscription cancelled
• subscription.renewed - Auto-renewal processed

OAuth Events

• oauth_client.created - New OAuth client
• oauth_client.deleted - Client removed
• oauth_client.token_revoked - Access revoked

User Events

• user.created - New user signed up
• user.updated - Profile changed
• user.deleted - User deleted account

Step 4: Save

1. Click "Create Webhook"
2. Copy the webhook secret
3. Store secret securely in your application

Webhook Payload

When an event occurs, Optare sends a POST request to your endpoint:

Headers

POST /webhooks/optare HTTP/1.1
Host: api.yourapp.com
Content-Type: application/json
X-Optare-Signature: sha256=<signature>
X-Optare-Event: organization.member.added
X-Optare-Delivery: uuid-of-delivery

Payload Example

{
  "event": "organization.member.added",
  "timestamp": "2025-11-30T12:00:00Z",
  "data": {
    "organization_id": "org_123",
    "member_id": "mem_456",
    "user": {
      "id": "user_789",
      "email": "john@example.com",
      "name": "John Doe"
    },
    "role": "member"
  }
}

Verifying Signatures

Always verify webhook signatures to ensure requests are from Optare.

Verification Process

import crypto from 'crypto';
 
function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return `sha256=${expectedSignature}` === signature;
}
 
// In your webhook handler
app.post('/webhooks/optare', (req, res) => {
  const signature = req.headers['x-optare-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook
  res.status(200).send('OK');
});

Responding to Webhooks

Success Response

Your endpoint should:

1. Respond within 10 seconds
2. Return HTTP 200-299 status code
3. Optionally return response body (not used)

// Good response
res.status(200).send('Webhook received');

Failure Handling

If your endpoint:

• Times out (>10s)
• Returns 4xx/5xx status
• Connection fails

Optare will retry with exponential backoff:

• Attempt 1: Immediate
• Attempt 2: After 1 minute
• Attempt 3: After 5 minutes
• Attempt 4: After 15 minutes
• Attempt 5: After 1 hour
• After 5 failed attempts, webhook is marked as failing

Managing Webhooks

Viewing Deliveries

1. Go to Settings → **Webhooks

** 2. Click on a webhook 3. View "Delivery History"

For each delivery, see:

• Timestamp
• Event type
• HTTP status code
• Response time
• Request/response payloads

Retry Failed Delivery

1. Find the failed delivery
2. Click "Retry"
3. Optare resends the event

Edit Webhook

1. Click "Edit" on webhook
2. Update:
   • Endpoint URL
   • Event subscriptions
   • Description
3. Save changes

Note: Cannot edit the secret. Regenerate instead.

Regenerate Secret

If secret is compromised:

1. Click "Regenerate Secret"
2. Copy new secret
3. Update your application BEFORE:
4. Confirm regeneration
5. Old secret becomes invalid

Disable Webhook

Temporarily stop deliveries:

1. Toggle webhook status to "Inactive"
2. No events will be sent
3. Re-enable anytime

Delete Webhook

Permanently remove:

1. Click "Delete"
2. Confirm deletion
3. Cannot be recovered

Testing Webhooks

Test Delivery

1. Go to webhook details
2. Click "Send Test Event"
3. Choose event type
4. Click "Send"
5. Check your endpoint receives it

Using Webhook Testing Tools

During development, use tools like:

• ngrok - Expose localhost
• webhook.site - Inspect payloads
• requestbin - Debug webhooks

Example with ngrok:

ngrok http 3000
# Use the HTTPS URL in Optare webhook config

Best Practices

For Reliability

1. Return 200 quickly - Process async to avoid timeouts
2. Verify signatures - Always validate requests
3. Idempotency - Handle duplicate deliveries gracefully
4. Logging - Keep delivery logs for debugging

Example: Async Processing

app.post('/webhooks/optare', async (req, res) => {
  // Verify signature
  if (!verifySignature(req)) {
    return res.status(401).send('Invalid');
  }
  
  // Respond immediately
  res.status(200).send('Acknowledged');
  
  // Process asynchronously
  processWebhookAsync(req.body).catch(err => {
    console.error('Webhook processing failed:', err);
  });
});

Security

1. Use HTTPS only - Protects data in transit
2. Verify all requests - Check signatures
3. Whitelist IP ranges - If possible
4. Rate limiting - Protect your endpoint
5. Secret rotation - Periodically regenerate

Troubleshooting

Webhook not receiving events?

• Verify webhook is "Active"
• Check event subscriptions include the event
• Ensure URL is correct and accessible
• Check firewall isn't blocking Optare

Deliveries failing?

• Check endpoint returns 200 within 10s
• Verify HTTPS certificate is valid
• Review server logs for errors
• Test with "Send Test Event"

Signature verification failing?

• Ensure using correct secret
• Verify payload isn't modified
• Check you're hashing the raw body
• Regenerate secret if compromised

Duplicate events?

• Deliveries may retry on network issues
• Use idempotency keys or deduplication
• Check X-Optare-Delivery header (unique per delivery)

Event Reference

See the full list of events and their payloads:

• Webhook Events Documentation

Next Steps

• API Keys - Alternative integration method
• Connected Apps - OAuth integration
• Audit Logs - View all events