Webhooks API

TIDALBAY's Webhooks API enables bi-directional event communication. Receive webhook notifications when scores change, and send custom events to TIDALBAY from your own systems.

Outbound Webhooks

Outbound webhooks notify your systems when events occur in TIDALBAY. Common use cases include syncing score changes to your SIEM, triggering workflows in your SOAR platform, and updating dashboards.

Configuring Outbound Webhooks

1. Navigate to Admin → Integrations → Webhooks
2. Click Create Webhook
3. Enter the destination URL
4. Select which events to subscribe to
5. Set the signing secret for verification
6. Click Save

Event Types

Payload Format

POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
X-TidalBay-Signature: sha256=<hmac_signature>
X-TidalBay-Event: score.band_changed
X-TidalBay-Delivery: <delivery_id>

{
  "event": "score.band_changed",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "employee_id": "emp_abc123",
    "email": "john.doe@company.com",
    "previous_score": 65,
    "new_score": 58,
    "previous_band": "yellow",
    "new_band": "orange",
    "trigger_event": "phishing_click"
  }
}

Verifying Signatures

All webhook payloads are signed with your webhook secret using HMAC-SHA256. Verify the signature to ensure the payload is authentic:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret)
      .update(payload)
      .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Inbound Webhooks

Inbound webhooks let you send custom events to TIDALBAY from systems not in our integration catalog.

Endpoint

POST https://api.tidalbay.com/v1/events/webhook
Authorization: Bearer <api_key>
Content-Type: application/json

Event Schema

{
  "source": "custom-system",
  "event_type": "policy_violation",
  "timestamp": "2025-01-15T10:30:00Z",
  "employee": {
    "email": "john.doe@company.com"
  },
  "details": {
    "description": "Accessed restricted file share",
    "severity": "medium",
    "metadata": {
      "file_path": "/shared/confidential/report.pdf"
    }
  }
}

Retry Policy

TIDALBAY retries failed webhook deliveries with exponential backoff:

• Attempt 1: Immediate
• Attempt 2: After 1 minute
• Attempt 3: After 5 minutes
• Attempt 4: After 30 minutes
• Attempt 5: After 2 hours

After 5 failed attempts, the delivery is marked as failed. Repeated failures will trigger a notification and may result in the webhook being automatically disabled.

Rate Limits

Next Steps

• API authentication guide
• View all integrations
• Create scoring rules for custom events