Webhooks

Webhooks allow your app to receive real-time notifications when events occur in Orbit AI. Build reactive integrations that respond instantly to form submissions and other events.

Available Events

submission.created

New form submission received

submission.updated

Submission data was modified

submission.deleted

Submission was deleted

form.created

New form was created

form.updated

Form configuration changed

form.deleted

Form was deleted

Webhook Payload

Each webhook delivers a JSON payload with event details:

Example Payload

{
  "event": "submission.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "submission_id": "sub_abc123",
    "form_id": "form_xyz789",
    "fields": {
      "email": "user@example.com",
      "name": "John Doe",
      "message": "Hello!"
    }
  }
}

Signature Verification

All webhook requests include a signature header for verification. Always verify the signature to ensure the request came from Orbit AI:

Node.js Signature Verification

const crypto = require('crypto');

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

Best Practices

Respond quickly

Return a 2xx response within 5 seconds. Process asynchronously if needed.

Verify signatures

Always validate the webhook signature before processing.

Handle retries

Webhooks are retried on failure. Implement idempotency to avoid duplicates.

Webhook Docs

Full webhook documentation

API Reference

Manage webhooks via API