Skip to main content

​
Overview

An inbound workflow webhook lets external systems (your backend, Zapier, Make, custom scripts) POST data into OrbitForms and run a specific workflow — without using the public form embed.
Inbound webhooks are always tied to a Form trigger. You must select a form on the workflow trigger first; the webhook accepts data in the exact same structure as that form’s fields.

​
What happens when data arrives

  1. OrbitForms validates the HMAC signature and payload structure
  2. A form submission is created (visible in your submissions list)
  3. Only that workflow runs — other form integrations (outbound webhooks, Slack, Zapier, etc.) are not triggered

​
Setup in the workflow builder

  1. Open your workflow and add a Form Submission trigger
  2. Select the form whose field structure you want to mirror
  3. In the trigger panel, enable Inbound Webhook
  4. Copy the Webhook URL and Signing Secret (the secret is shown once — save it securely)
The trigger panel displays the exact JSON structure required, keyed by each field’s name (not label).

​
Endpoint

POST https://orbitforms.ai/api/webhooks/inbound/{token}
Each workflow gets a unique {token} when you enable the inbound webhook.

​
Required headers

HeaderDescription
Content-Typeapplication/json
X-Orbit-SignatureHMAC-SHA256 signature of the raw request body: sha256=<hex>
X-Orbit-Timestamp(Optional) Unix timestamp in milliseconds — rejected if older than 5 minutes

​
Payload structure

Send a flat JSON object where each key is a form field name: 
{
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Doe",
  "company": "Acme Inc",
  "interests": ["Product A", "Product B"]
}

​
Field types

Form field typeJSON typeExample
Text, email, phone, URL, textarea, number, date, time, dropdown, multiple choicestring"[email protected]"
Multi-selectstring[]["Option 1", "Option 2"]
Strict validation
  • Only field names from the selected form are allowed
  • Required fields must be present and non-empty
  • System keys starting with _ are rejected
  • Unknown fields return a 422 error with details

​
Signing requests

Compute the signature over the exact raw JSON body (before parsing): 
const crypto = require('crypto');

function signPayload(rawBody, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(rawBody, 'utf8');
  return `sha256=${hmac.digest('hex')}`;
}

const body = JSON.stringify({
  email: '[email protected]',
  first_name: 'Jane',
  last_name: 'Doe',
});

const signature = signPayload(body, process.env.ORBIT_WEBHOOK_SECRET);
const timestamp = Date.now().toString();

// Send with fetch, axios, etc.

import hmac
import hashlib
import json
import time

def sign_payload(raw_body: str, secret: str) -> str:
    digest = hmac.new(secret.encode(), raw_body.encode(), hashlib.sha256).hexdigest()
    return f"sha256={digest}"

body = json.dumps({"email": "[email protected]", "first_name": "Jane"})
signature = sign_payload(body, os.environ["ORBIT_WEBHOOK_SECRET"])
timestamp = str(int(time.time() * 1000))
The signing algorithm matches outbound webhook verification. Use the same HMAC-SHA256 approach with your inbound webhook secret.

​
cURL example

Replace {token}, {secret}, and field values with your workflow’s values: 
BODY='{"email":"[email protected]","first_name":"Jane","last_name":"Doe"}'
TIMESTAMP=$(date +%s000)
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "YOUR_SECRET" | sed 's/^.* //')
SIGNATURE="sha256=$SIGNATURE"

curl -X POST "https://orbitforms.ai/api/webhooks/inbound/{token}" \
  -H "Content-Type: application/json" \
  -H "X-Orbit-Signature: $SIGNATURE" \
  -H "X-Orbit-Timestamp: $TIMESTAMP" \
  -d "$BODY"

​
Responses

​
Success (200)

{
  "success": true,
  "submission_id": "550e8400-e29b-41d4-a716-446655440000",
  "workflow_id": "660e8400-e29b-41d4-a716-446655440001"
}

​
Error codes

StatusMeaning
401Missing or invalid X-Orbit-Signature
404Webhook token not found or disabled
413Request body exceeds 1 MB
422Payload validation failed — see details array
429Rate limit exceeded (100 requests/minute per team)
500Server error
Example validation error: 
{
  "error": "Payload validation failed",
  "details": [
    "Required field \"email\" is missing or empty",
    "Unknown field \"unknown_field\""
  ]
}

​
Rotating the signing secret

In the workflow trigger panel, use Rotate secret to generate a new signing secret. Update your external system immediately — requests signed with the old secret will fail.

​
Disabling the webhook

Toggle off Inbound Webhook in the trigger panel, or delete the workflow. The URL becomes invalid immediately.

Outbound Webhooks

Receive events when forms are submitted (Orbit → your server)

Webhook Security

HMAC signature verification details

Workflows Guide

Build and manage automation workflows

Form Fields

Understand field names and types