Webhooks
Overview
A FormKiQ webhook is an intake endpoint. An external system, a web form, or another service posts data to the webhook URL, and FormKiQ stores that payload as a new document. From there the document behaves like any other: it can be tagged, processed by document actions, routed by rulesets, and moved through workflows.
Use a webhook when the sender can make an HTTP POST but should not, or cannot, use the full document API. Typical senders are web forms, SaaS products that offer "send a webhook" integrations, and partner systems.
Webhooks receive data into FormKiQ. To notify another system when something happens to a document, use document events or a workflow step instead.
How a Webhook Works
- You create a webhook with
POST /webhooks. FormKiQ returns awebhookId. GET /webhooks/{webhookId}returns the webhook'surl. Give that URL to the sender.- The sender posts a payload to the URL.
- FormKiQ stores the payload as a new document and returns its
documentId.
The document created from a post has:
| Property | Value |
|---|---|
| Content | The request body, exactly as sent. |
| Content type | The Content-Type of the request. |
| Path | webhooks/{webhookId} |
| Site | The site the webhook belongs to. |
The document is created asynchronously. The documentId is returned immediately, but the document can take a moment to appear in listings and search.
A webhook belongs to one site. For a site other than default, the webhook URL includes ?siteId=...; keep that query parameter when you hand out the URL.
Public and Private Webhooks
The enabled property decides who may post to a webhook.
enabled | URL | Who can post |
|---|---|---|
"true" (default) | /public/webhooks/{webhookId} | Anyone who has the URL. No authentication. |
"private" | /private/webhooks/{webhookId} | Authenticated callers with the WRITE_WEBHOOKS permission. |
"false" | — | No one. Posts are rejected until the webhook is enabled again. |
Public endpoints are disabled by default. They work only when the deployment was installed with the EnablePublicUrls CloudFormation parameter set to true; see Quick Start. If your deployment does not enable public URLs, use private webhooks.
A private webhook must be called on the private URL with an Authorization header. Posting to a private webhook through the public URL is refused.
Create and Manage Webhooks
curl -X POST "${HTTP_API_URL}/webhooks?siteId=${SITE_ID}" \
-H "Authorization: ${AUTHORIZATION_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"name": "Partner invoice intake",
"enabled": "private"
}'
| Property | Required | Description |
|---|---|---|
name | Yes | A label for the webhook. |
enabled | No | "true", "private", or "false". Defaults to "true". |
ttl | No | Lifetime of the webhook in seconds, counted from the time it is set. See Expiry. |
tags | No | Tags stored on the webhook, as key and value pairs. |
Other operations:
| Operation | Endpoint | Permission |
|---|---|---|
| List webhooks | GET /webhooks | READ_WEBHOOKS |
Get one webhook, including its url | GET /webhooks/{webhookId} | READ_WEBHOOKS |
Update name, enabled, or ttl | PATCH /webhooks/{webhookId} | WRITE_WEBHOOKS |
| Delete a webhook | DELETE /webhooks/{webhookId} | DELETE_WEBHOOKS |
| List or add webhook tags | GET / POST /webhooks/{webhookId}/tags | READ_WEBHOOKS / WRITE_WEBHOOKS |
Choose public or private when you create the webhook.
Updating enabled supports public-enabled/disabled values and does not preserve the "private" mode. A private webhook re-enabled as true can accept unauthenticated posts through its public URL when public URLs are enabled for the deployment.
To pause private intake, disable or delete the webhook. When intake resumes, create a new webhook with "enabled": "private", give the sender its new URL, and retire the disabled webhook.
In FormKiQ Web, webhooks are managed under Orchestration → Intake webhooks. See Orchestration.
Post to a Webhook
Send the payload as the request body. JSON and form posts are both accepted.
curl -X POST "${HTTP_API_URL}/private/webhooks/${WEBHOOK_ID}?siteId=${SITE_ID}" \
-H "Authorization: ${AUTHORIZATION_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"invoiceNumber": "INV-1001", "amount": 1250.00}'
{
"documentId": "b1b4c8f2-0d5c-4b0e-8a6a-2c7f6f0f6e11"
}
Avoid Duplicates on Retry
Senders often retry when they do not receive a response. Add an Idempotency-Key header with a value that is unique to the payload. If the same key is received again shortly afterward, FormKiQ returns the original documentId and does not create a second document.
HTML Forms and Redirects
An HTML form can post straight to a public webhook. Add a redirect_uri query parameter to send the browser to a confirmation page after the post instead of showing the JSON response.
<form method="post"
action="https://your-formkiq-api.example.com/public/webhooks/WEBHOOK_ID?redirect_uri=https%3A%2F%2Fexample.com%2Fthanks">
<input name="email" type="email" />
<button type="submit">Send</button>
</form>
For form posts you can also add responseFields, a comma-separated list of form field names. Those fields are appended to the redirect URL as query parameters, so the confirmation page can display them.
Expiry
A webhook can be given a limited lifetime with ttl, in seconds. After that time the webhook URL stops accepting posts. If you do not set ttl, the site's default webhook lifetime applies when one is configured; otherwise the webhook does not expire.
A document created through a webhook that has an expiry carries the same expiry time and is removed when it passes. If the webhook has no expiry, the site's default document lifetime applies when one is configured.
Use a short ttl for one-off intake, such as a link sent to a single customer. Do not set a ttl on a webhook whose documents you need to keep unless that is the intent.
Limits
A site can cap the number of webhooks. When the limit is reached, creating another webhook returns 429. In FormKiQ Web the cap is Maximum webhooks under Administration → Workspaces → General & limits.
Responses
| Status | Meaning |
|---|---|
200 | The payload was accepted. The body contains documentId. |
301 | The payload was accepted and redirect_uri was supplied. |
400 | The webhook ID is unknown or the webhook has expired, or the body was sent as JSON but is not valid JSON. |
401 | The webhook is private and was called without valid authentication or on the public URL. |
429 | The webhook is disabled. On POST /webhooks, the site has reached its webhook limit. |
Security
- Treat a public webhook URL as a secret. Anyone who has it can create documents in your site. Share it only with the intended sender, and rotate it by deleting the webhook and creating a new one.
- Prefer private webhooks when the sender can send an
Authorizationheader. Give that caller a credential limited toWRITE_WEBHOOKS; see Manage API Keys. - Validate what arrives. A webhook stores whatever is posted. Use a ruleset or workflow to check the payload before other systems rely on it, and run malware scanning on content from untrusted senders.
- Preserve private-only access deliberately. In v1.19.2, do not disable and re-enable a private webhook expecting it to remain private. Recreate it with
"enabled": "private"and retire the old URL. Public webhooks can be disabled and re-enabled when retaining their URL is appropriate. - Set a site limit and a
ttlfor public intake so that a leaked URL has a bounded effect.
Troubleshooting
| Problem | Likely cause | What to check |
|---|---|---|
400 invalid webhook url | Wrong webhook ID, missing siteId, or the webhook expired. | Compare the URL with the url from GET /webhooks/{webhookId}. |
401 on a public URL | The webhook is private. | Post to the /private/webhooks/ URL with an Authorization header. |
429 webhook is disabled | enabled is "false". | A public webhook can be re-enabled. For private-only intake, create a new private webhook rather than re-enabling it as true. |
| Public URL returns an authorization error for every webhook | Public URLs are not enabled for the deployment. | Check the EnablePublicUrls stack parameter, or use private webhooks. |
| The document is not visible yet | Creation is asynchronous. | Retry GET /documents/{documentId} after a short wait. |
| Documents created by a webhook disappear | The webhook, or the site, has a time to live. | Check the webhook's ttl and the site configuration. |
API Reference
- Add webhook
- Get webhooks
- Get webhook
- Update webhook
- Delete webhook
- Post to a private webhook
- Post to a public webhook