Webhooks

What are Webhooks?

Webhooks allow you to build or set up integrations that subscribe to certain events in OAuth42. When one of those events is triggered, OAuth42 sends an HTTP POST payload to the webhook's configured URL.

Webhooks can be used to update an external tracker, trigger CI/CD pipelines, update a backup mirror, or even deploy to your production server.

Setting Up Webhooks

1. Create a Webhook Endpoint

First, create an HTTPS endpoint in your application that can receive POST requests:

// Express.js example
app.post('/webhooks/oauth42', async (req, res) => {
  const signature = req.headers['x-oauth42-signature'];
  const payload = req.body;

  // Verify webhook signature
  if (!verifySignature(payload, signature)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  switch (payload.event_type) {
    case 'user.created':
      await handleUserCreated(payload.data);
      break;
    case 'user.login':
      await handleUserLogin(payload.data);
      break;
    // ... handle other events
  }

  res.status(200).send('OK');
});

2. Register Your Webhook

In your OAuth42 dashboard:

1. Navigate to Settings → Webhooks
2. Click "Add Webhook"
3. Enter your endpoint URL (must be HTTPS)
4. Select the events you want to subscribe to
5. Save your webhook configuration

3. Verify Signatures

OAuth42 signs each webhook payload with a secret key. Verify the signature to ensure the webhook came from OAuth42:

import crypto from 'crypto';

function verifySignature(payload, signature) {
  const secret = process.env.OAUTH42_WEBHOOK_SECRET;
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computedSignature)
  );
}

Available Events

Payload Examples

{
  "event_id": "evt_1234567890abcdef",
  "event_type": "user.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "api_version": "2024-01-01",
  "data": {
    "user_id": "usr_abcd1234",
    "email": "[email protected]",
    "username": "johndoe",
    "email_verified": false,
    "mfa_enabled": false,
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Best Practices

Testing Webhooks

You can test your webhook endpoint using the OAuth42 dashboard:

1. Go to Settings → Webhooks
2. Select your webhook configuration
3. Click "Send Test Event"
4. Choose an event type and send
5. Verify your endpoint received and processed the test event

For local development, use tools like ngrok to expose your local server to the internet temporarily.