> ## 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 data to any endpoint

<Note>
  Webhooks are a **Pro** plan feature.
</Note>

## Start Here

Webhooks let you send form submission data to any URL in real-time. This is perfect for building custom integrations, connecting to internal systems, or triggering complex automation workflows. This guide shows you how to set up and secure webhooks.

### Overview

Here's the idea in plain terms:

* You provide a **webhook URL** where OrbitForms should send data.
* When someone submits a form, Orbit sends a **POST request** with the submission data.
* Your server receives the data and processes it however you need.
* We include authentication headers so you can verify requests are from Orbit.

### Why This Matters

Webhooks give you complete flexibility. Connect to any backend, internal tool, or custom service — even systems we don't have native integrations for. They're perfect for developers who need full control over their data flow.

***

## Step 1: Create Your Webhook Endpoint

First, set up a URL on your server that can receive POST requests.

**What to do:**

* Create an endpoint on your server that accepts POST requests.
* The endpoint must be publicly accessible (not localhost).
* The URL must use HTTPS for security.

**What this does:**

* Creates a destination for your form data.
* Your server can then process, store, or forward the data as needed.

<Warning>
  Your endpoint must respond with a 2xx status code (like 200) to confirm receipt. If it doesn't, we'll retry the webhook.
</Warning>

***

## Step 2: Add the Webhook in Orbit

Now configure OrbitForms to send data to your endpoint.

**What to do in Orbit:**

1. Go to your form and click the **Integrations** tab.
2. Click **Add Integration** and select **Webhook**.
3. Enter your **Webhook URL** (must be HTTPS).
4. Optionally add authentication headers (see Authentication section below).
5. Click **Test Webhook** to verify it works.
6. Click **Save** to enable the webhook.

***

## Payload Format

Webhooks send a POST request with a JSON body containing the form submission data:

```json theme={null}
{
  "event": "submission.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "form_id": "550e8400-e29b-41d4-a716-446655440000",
    "form_title": "Contact Form",
    "form_slug": "contact",
    "submission_id": "660e8400-e29b-41d4-a716-446655440001",
    "submission_data": {
      "email": "john@example.com",
      "name": "John Doe",
      "message": "Hello, I have a question..."
    },
    "submitted_at": "2024-01-15T10:30:00Z",
    "metadata": {
      "referrer": "https://yoursite.com/contact",
      "device_type": "desktop",
      "utm_source": "google"
    }
  }
}
```

<Tip>
  The `submission_data` object contains all form fields exactly as submitted. Field names match your form field labels.
</Tip>

***

## Authentication

Secure your webhook endpoint by adding authentication headers. We recommend using at least one of these methods:

### Bearer Token

```
Authorization: Bearer your-secret-token
```

### API Key Header

```
X-API-Key: your-api-key
```

### Webhook Signature

Each webhook includes a signature header you can use to verify the request came from Orbit:

```
X-Orbit-Signature: sha256=...
```

***

## Retry Logic

If your webhook endpoint returns an error or doesn't respond, OrbitForms automatically retries:

### Retry Schedule

| Retry     | Timing                         |
| --------- | ------------------------------ |
| 1st retry | 1 minute after initial failure |
| 2nd retry | 1 minute after 1st retry       |
| 3rd retry | 1 minute after 2nd retry       |

<Tip>
  If all retries fail, check your endpoint logs for errors. Common issues include timeouts, invalid responses, or authentication problems.
</Tip>

***

## Common Issues and Fixes

<AccordionGroup>
  <Accordion title="Webhook not receiving data">
    * Verify your endpoint URL is correct and publicly accessible.
    * Check that your server is accepting POST requests.
    * Make sure your URL uses HTTPS (HTTP is not supported).
  </Accordion>

  <Accordion title="Webhook keeps retrying">
    * Your endpoint must return a 2xx status code (like 200).
    * 4xx and 5xx responses will trigger retries.
    * Check your server logs for errors processing the request.
  </Accordion>

  <Accordion title="Request timing out">
    * Webhooks timeout after 30 seconds.
    * Return a quick response, then process data asynchronously.
    * Avoid slow database queries or external API calls during the request.
  </Accordion>
</AccordionGroup>

### Response Status Codes

| Code | Meaning                        |
| ---- | ------------------------------ |
| 200  | Success - submission delivered |
| 400  | Bad request - will not retry   |
| 500  | Server error - will retry      |

***

## Related Articles

<CardGroup cols={2}>
  <Card title="Zapier Integration" icon="https://mintcdn.com/orbitai-d647f397/T1yKN7sdBmMTM8cv/_images/integrations/zapier.svg?fit=max&auto=format&n=T1yKN7sdBmMTM8cv&q=85&s=57b79caa02205dedaf6c8b879067976a" href="/integrations/zapier" width="28" height="28" data-path="_images/integrations/zapier.svg">
    Connect to 5,000+ apps with no code
  </Card>

  <Card title="HubSpot Integration" icon="https://mintcdn.com/orbitai-d647f397/T1yKN7sdBmMTM8cv/_images/integrations/HubSpot.svg?fit=max&auto=format&n=T1yKN7sdBmMTM8cv&q=85&s=1fdf3aa6d2c9545d9ce8348dfc8ed927" href="/integrations/hubspot" width="524" height="524" data-path="_images/integrations/HubSpot.svg">
    Connect to HubSpot CRM
  </Card>

  <Card title="Workflow Features" icon="bolt" href="/guides/workflows">
    Automate with built-in workflows
  </Card>

  <Card title="All Integrations" icon="webhook" href="/integrations">
    Browse all available integrations
  </Card>
</CardGroup>