Webhooks

Webhooks let you receive HTTP notifications whenever something happens in FormFlows.ai — a form is published, a submission is created, or a submission is updated. When an event occurs, FormFlows.ai sends a POST request with a JSON payload to your registered URL.

Register a webhook

POST /webhooks Registers a new webhook endpoint.

Body parameters

string

required

The HTTPS URL that FormFlows.ai will send event payloads to. Must be publicly accessible.

string[]

required

Array of event types to subscribe to. Supported events:

submission.created — A new submission is received on a form.
submission.updated — An existing submission is modified.
form.published — A form’s status changes to published.

string

Restrict this webhook to events from a specific form. Omit to receive events from all forms in your account.

string

A signing secret you choose. If provided, FormFlows.ai signs every payload with HMAC-SHA256 using this secret and includes the signature in the X-FormFlows-Signature header. Use this to verify that payloads genuinely come from FormFlows.ai.

Response

string

Unique webhook identifier, prefixed with whk_.

string

The registered endpoint URL.

string[]

List of event types this webhook is subscribed to.

string

The form this webhook is scoped to. null if it receives events from all forms.

string

ISO 8601 creation timestamp.

curl --request POST \
  --url "https://api.formflows.ai/v1/webhooks" \
  --header "Authorization: Bearer sk_live_your_api_key" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://hooks.yourapp.com/formflows",
    "events": ["submission.created", "form.published"],
    "form_id": "frm_8kQmP2xNvL",
    "secret": "whsec_your_signing_secret"
  }'

import requests

payload = {
    "url": "https://hooks.yourapp.com/formflows",
    "events": ["submission.created", "form.published"],
    "form_id": "frm_8kQmP2xNvL",
    "secret": "whsec_your_signing_secret",
}

response = requests.post(
    "https://api.formflows.ai/v1/webhooks",
    headers={"Authorization": "Bearer sk_live_your_api_key"},
    json=payload,
)

webhook = response.json()
print("Registered webhook:", webhook["id"])

Example response:

{
  "id": "whk_6mNoP8qRsT",
  "url": "https://hooks.yourapp.com/formflows",
  "events": ["submission.created", "form.published"],
  "form_id": "frm_8kQmP2xNvL",
  "secret_set": true,
  "created_at": "2025-01-15T12:00:00Z"
}

The secret value you provide is never returned in API responses. The secret_set boolean confirms whether a signing secret is configured.

List webhooks

GET /webhooks Returns all registered webhooks in your account.

Query parameters

integer

default:"20"

Number of webhooks to return per page. Maximum 100.

string

Pagination cursor from a previous response’s next_cursor.

curl --request GET \
  --url "https://api.formflows.ai/v1/webhooks" \
  --header "Authorization: Bearer sk_live_your_api_key"

import requests

response = requests.get(
    "https://api.formflows.ai/v1/webhooks",
    headers={"Authorization": "Bearer sk_live_your_api_key"},
)

result = response.json()
for webhook in result["data"]:
    print(webhook["id"], webhook["url"], webhook["events"])

Delete a webhook

DELETE /webhooks/{id} Removes a registered webhook. FormFlows.ai will stop sending events to that endpoint immediately.

Path parameters

string

required

The webhook ID to delete, e.g. whk_6mNoP8qRsT.

Response

Returns a 204 No Content response on success.

curl --request DELETE \
  --url "https://api.formflows.ai/v1/webhooks/whk_6mNoP8qRsT" \
  --header "Authorization: Bearer sk_live_your_api_key"

import requests

response = requests.delete(
    "https://api.formflows.ai/v1/webhooks/whk_6mNoP8qRsT",
    headers={"Authorization": "Bearer sk_live_your_api_key"},
)

if response.status_code == 204:
    print("Webhook deleted.")

Webhook payload format

When a subscribed event occurs, FormFlows.ai sends a POST request to your URL with the following JSON body:

{
  "event": "submission.created",
  "form_id": "frm_8kQmP2xNvL",
  "timestamp": "2025-01-15T14:32:00Z",
  "data": {
    "submission_id": "sub_7vHnM4rKpQ",
    "fields": {
      "fld_a1B2c3D4": "Jane Smith",
      "fld_e5F6g7H8": "[email protected]",
      "fld_i9J0k1L2": ["Keynote", "Workshop A"]
    }
  }
}

Payload fields

string

The event type that fired. One of submission.created, submission.updated, or form.published.

string

The ID of the form that the event is associated with.

string

ISO 8601 timestamp of when the event occurred.

object

Event-specific data.

Show data properties for submission.created / submission.updated

string

The ID of the submission that was created or updated.

object

Key-value map of field IDs to submitted values.

Show data properties for form.published

string

The name of the form that was published.

string

ISO 8601 timestamp of when the form was published.

Signature verification

If you set a secret when registering your webhook, every request includes an X-FormFlows-Signature header:

X-FormFlows-Signature: sha256=3d2f8c1e9b4a...

The value is sha256= followed by the hex-encoded HMAC-SHA256 of the raw request body, computed using your secret as the key. Always verify this signature before processing a payload to confirm it came from FormFlows.ai.

Compare signatures using a constant-time comparison function. Using a regular string equality check (==) is vulnerable to timing attacks.

import hashlib
import hmac

def verify_signature(payload_body: bytes, signature_header: str, secret: str) -> bool:
    """Verify the X-FormFlows-Signature header against the request body."""
    expected_sig = hmac.new(
        secret.encode("utf-8"),
        payload_body,
        hashlib.sha256,
    ).hexdigest()

    received_sig = signature_header.removeprefix("sha256=")

    return hmac.compare_digest(expected_sig, received_sig)


# Example usage in a Flask handler
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_your_signing_secret"

@app.route("/formflows", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-FormFlows-Signature", "")

    if not verify_signature(request.get_data(), signature, WEBHOOK_SECRET):
        abort(400, "Invalid signature")

    event = request.json
    print(f"Received event: {event['event']}")
    return "", 200

const crypto = require("crypto");

function verifySignature(rawBody, signatureHeader, secret) {
  const expectedSig = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  const receivedSig = signatureHeader.replace("sha256=", "");

  // Use timingSafeEqual to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(expectedSig, "hex"),
    Buffer.from(receivedSig, "hex")
  );
}

// Example usage in an Express handler
const express = require("express");
const app = express();
const WEBHOOK_SECRET = "whsec_your_signing_secret";

app.post("/formflows", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-formflows-signature"] || "";

  if (!verifySignature(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(400).send("Invalid signature");
  }

  const event = JSON.parse(req.body);
  console.log("Received event:", event.event);
  res.status(200).send();
});

Retry policy

FormFlows.ai considers a delivery successful when your endpoint returns any 2xx HTTP status code within 10 seconds. If the request times out or returns a non-2xx status, FormFlows.ai retries the delivery with exponential backoff:

Attempt	Delay
1 (initial)	Immediate
2	30 seconds
3	5 minutes
4	30 minutes
5	2 hours

After 5 failed attempts, the event is marked as undeliverable and no further retries occur.

Your endpoint must respond within 10 seconds. If your processing logic takes longer than that, return a 200 immediately and handle the payload asynchronously (e.g., push it to a queue).

Because retries can deliver the same event more than once, make your handler idempotent. Use data.submission_id or timestamp to detect and skip duplicate deliveries.

Overview

Endpoints

Register a webhook

Body parameters

Response

List webhooks

Query parameters

Delete a webhook

Path parameters

Response

Webhook payload format

Payload fields

Signature verification

Retry policy

​Register a webhook

​Body parameters

​Response

​List webhooks

​Query parameters

​Delete a webhook

​Path parameters

​Response

​Webhook payload format

​Payload fields

​Signature verification

​Retry policy

Register a webhook

Body parameters

Response

List webhooks

Query parameters

Delete a webhook

Path parameters

Response

Webhook payload format

Payload fields

Signature verification

Retry policy