Form webhooks

SagePigeon can POST every submission on a form to an https endpoint you run, as JSON, signed with a secret only you and SagePigeon know. Use it to put leads in your own database, open a ticket, or start any job your code can start. Webhooks are on Pro and Scale.

The request

HTTP
POST https://hooks.example.com/formsage
content-type: application/json
user-agent: SagePigeon/1.0
formsage-timestamp: 1791540000
formsage-signature: sha256=5c1f…
JSON
{
  "event": "submission.received",
  "formId": "jdfy7yd2mcwt",
  "submissionId": "…",
  "createdAt": "2026-10-11T09:14:22.000Z",
  "data": {
    "name": "Priya Raman",
    "email": "priya@example.com",
    "message": "Could you cater a weekday lunch for 40?"
  },
  "meta": {
    "ip": "203.0.113.42",
    "userAgent": "Mozilla/5.0 …",
    "referer": "https://example.com/contact",
    "country": "GB",
    "locale": "en-GB"
  },
  "attachments": [],
  "routedTo": ["events@example.com"]
}

data holds exactly what the visitor submitted, minus the honeypot field and SagePigeon's own fields. routedTo lists who the notification went to after routing rules ran. meta fields are present when the request carried them.

Verify the signature

The signature is an HMAC-SHA256, in hex, of the timestamp, a dot, and the raw request body, keyed with the form's signing secret. Check it before you trust anything in the body, compare in constant time, and reject old timestamps. An Express example:

JavaScript
import express from 'express'
import { createHmac, timingSafeEqual } from 'node:crypto'

const app = express()

app.post('/formsage', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('formsage-timestamp') ?? ''
  const signature = req.get('formsage-signature') ?? ''
  const expected =
    'sha256=' +
    createHmac('sha256', process.env.FORMSAGE_SIGNING_SECRET)
      .update(`${timestamp}.${req.body}`)
      .digest('hex')

  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300
  const valid =
    signature.length === expected.length &&
    timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  if (!fresh || !valid) return res.sendStatus(401)

  const submission = JSON.parse(req.body)
  // store it, open a ticket, …
  res.sendStatus(200)
})

Use the raw body. Parsing the JSON and serialising it again changes spacing and key order, and the signature will not match.

Set it up

  1. Open the form, go to Settings, then Integrations.
  2. Under Webhook, type your endpoint's https address and press Save integrations.
  3. The signing secret appears under the address. Press Copy signing secret and put it in your endpoint's environment.
  4. On the Setup tab, press Send a test submission and check that your endpoint answers with a 2xx status.

Rotate beside the secret makes a new one. The old one stops working at once, so update your endpoint first. A delivery your endpoint refuses in between is tried again, signed with the new secret.

Make, n8n and your own subscriber

The same signed submissions can go to any number of subscribers through REST hooks. Make, n8n or your own service can subscribe with an API key:

HTTP
POST /api/v1/hooks
x-api-key: fsk_…
{ "targetUrl": "https://hook.example.com/abc", "formId": "FORM_ID", "source": "make" }
→ 201 { "id": "…", "event": "submission.received", … }

DELETE /api/v1/hooks/:id

Leave out formId to receive every form in the workspace. The REST hook payload is flat, with each answer at the top level beside id, form_id, form_name, submitted_at, routed_to, ip and attachments, because flat fields are easier to map in no-code tools. It carries the same signature headers when the form has a webhook signing secret. Every subscription is listed on the workspace's Integrations page (open Settings in the sidebar, then Integrations), with the last time it fired and a Remove button.

Make the key under Sending → API keys with Allow writes ticked. A read-only key is refused with "This API key is read-only".

Plans

Webhooks, REST hooks and API keys are on Pro ($49 a month) and Scale ($149 a month). See pricing.

Limits and gotchas

  • https only for the form webhook, and the address must be public. SagePigeon checks it when you save and again before each delivery.
  • 10-second timeout. Answer quickly with a 2xx and do slow work afterwards.
  • A failed delivery is tried again, 5 times in all. A non-2xx answer, a timeout or a connection error is retried after 30 seconds, then 2 minutes, 10 minutes and 15 minutes, so the whole run takes about half an hour. Each attempt sends the same body with a fresh timestamp and signature. Only the webhook is retried. The notification email is not sent again, and a destination that already took the submission does not get it twice.
  • Every attempt is in the delivery log. The submission's log reads "attempt 1 of 5, trying again in 30 seconds", then "delivered on attempt 3" when it gets through. If the fifth attempt fails, the submission is marked partly delivered and the form's Health tab counts it under "Not accepted on delivery". Fix the endpoint, then read what it missed through the management API.
  • Expect the occasional repeat. An endpoint that saved the request but answered after 10 seconds counts as failed and gets it again. Keep the submissionId and skip one you have already handled.
  • Forms that remove contents on delivery are not retried once the contents are gone. The log says the delivery was not sent again, so you never receive an empty submission.
  • REST hooks that keep failing are removed once 10 submissions in a row have failed every attempt. A target that answers 410 Gone, which is what a deleted Zap returns, is removed at once and not retried, and the delivery log shows it as rejected.
  • Not sent on manual re-sends. When someone re-sends a failed notification email from the dashboard, webhooks are not fired again, so that never shows your endpoint one submission twice.

Webhooks are on Pro.

See pricing, or start free and upgrade when your endpoint is ready.