> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitforms.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Send form submission data to any URL in real-time. Perfect for custom backends, internal tools, or services without native integrations.

<Note>
  Webhooks require the **Pro** plan or higher.
</Note>

## What are Webhooks?

Webhooks are HTTP callbacks that send data to a URL you specify when events occur—such as a form submission. OrbitForms webhooks let you:

* **Real-time** — Data is sent immediately when a submission is received
* **Flexible** — Works with any service that accepts HTTP POST requests
* **Secure** — Verify requests using HMAC-SHA256 signatures
* **Retries** — Automatic retries if your endpoint fails

## Setting Up a Webhook

<Steps>
  <Step title="Open your form">
    Open the form you want to send webhook data from.
  </Step>

  <Step title="Go to Integrations">
    Click **Integrations** in the form settings or sidebar.
  </Step>

  <Step title="Add Webhook">
    Click **Add Webhook** or **Webhook**.
  </Step>

  <Step title="Enter your URL">
    Enter the full endpoint URL (e.g., `https://your-server.com/webhook`).
  </Step>

  <Step title="Configure optional settings">
    Add custom headers or adjust the payload format if needed.
  </Step>

  <Step title="Save and test">
    Save the webhook and submit a test form to verify it works.
  </Step>

  <Step title="Copy your signing secret">
    Copy the webhook signing secret to verify requests on your server.
  </Step>
</Steps>

## Payload Format

Each webhook request is sent as a JSON payload with the following structure:

```json theme={null}
{
  "event": "form.submitted",
  "timestamp": "2025-03-07T12:00:00.000Z",
  "form_id": "abc123",
  "form_name": "Contact Form",
  "submission_id": "sub_xyz789",
  "data": {
    "email": "user@example.com",
    "name": "Jane Doe",
    "message": "Hello, I'd like to learn more."
  }
}
```

| Field           | Description                                 |
| --------------- | ------------------------------------------- |
| `event`         | The event type (e.g., `form.submitted`)     |
| `timestamp`     | ISO 8601 timestamp                          |
| `form_id`       | Unique form identifier                      |
| `form_name`     | Display name of the form                    |
| `submission_id` | Unique submission identifier                |
| `data`          | Form field values keyed by field ID or name |

## Security & Verification

OrbitForms signs each webhook request with HMAC-SHA256. Verify the signature before processing.

### Signature Header

The signature is sent in the `X-Orbit-Signature` header.

### Verification Steps

1. **Get the raw request body** — Use the raw bytes as received (do not parse and re-serialize JSON)
2. **Compute HMAC-SHA256** — Using your webhook signing secret as the key
3. **Compare with the header** — The header value should match your computed signature
4. **Reject if mismatched** — Do not process requests with invalid signatures

Example (Node.js):

```javascript theme={null}
const crypto = require('crypto');

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

## Error Handling & Retries

### Success Response

Your endpoint should return a **2xx** status code (e.g., 200, 201, 204) to indicate successful processing.

### Automatic Retries

If your endpoint returns a non-2xx status or times out, OrbitForms will retry up to **3 times** with exponential backoff.

### Timeout

Requests time out after **30 seconds**. Ensure your endpoint responds within this window.

## Next Steps

<CardGroup cols={2}>
  <Card title="Integrations" icon="plug" href="/guides/integrations">
    Connect to CRMs, Slack, and more
  </Card>

  <Card title="API Reference" icon="zap" href="/guides/api-reference">
    Programmatic access to forms and submissions
  </Card>
</CardGroup>