Skip to main content

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.

note

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​

  1. You create a webhook with POST /webhooks. FormKiQ returns a webhookId.
  2. GET /webhooks/{webhookId} returns the webhook's url. Give that URL to the sender.
  3. The sender posts a payload to the URL.
  4. FormKiQ stores the payload as a new document and returns its documentId.

The document created from a post has:

PropertyValue
ContentThe request body, exactly as sent.
Content typeThe Content-Type of the request.
Pathwebhooks/{webhookId}
SiteThe 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.

enabledURLWho 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"
}'
PropertyRequiredDescription
nameYesA label for the webhook.
enabledNo"true", "private", or "false". Defaults to "true".
ttlNoLifetime of the webhook in seconds, counted from the time it is set. See Expiry.
tagsNoTags stored on the webhook, as key and value pairs.

Other operations:

OperationEndpointPermission
List webhooksGET /webhooksREAD_WEBHOOKS
Get one webhook, including its urlGET /webhooks/{webhookId}READ_WEBHOOKS
Update name, enabled, or ttlPATCH /webhooks/{webhookId}WRITE_WEBHOOKS
Delete a webhookDELETE /webhooks/{webhookId}DELETE_WEBHOOKS
List or add webhook tagsGET / POST /webhooks/{webhookId}/tagsREAD_WEBHOOKS / WRITE_WEBHOOKS

Choose public or private when you create the webhook.

Private webhook updates in v1.19.2

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​

StatusMeaning
200The payload was accepted. The body contains documentId.
301The payload was accepted and redirect_uri was supplied.
400The webhook ID is unknown or the webhook has expired, or the body was sent as JSON but is not valid JSON.
401The webhook is private and was called without valid authentication or on the public URL.
429The 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 Authorization header. Give that caller a credential limited to WRITE_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 ttl for public intake so that a leaked URL has a bounded effect.

Troubleshooting​

ProblemLikely causeWhat to check
400 invalid webhook urlWrong webhook ID, missing siteId, or the webhook expired.Compare the URL with the url from GET /webhooks/{webhookId}.
401 on a public URLThe webhook is private.Post to the /private/webhooks/ URL with an Authorization header.
429 webhook is disabledenabled 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 webhookPublic URLs are not enabled for the deployment.Check the EnablePublicUrls stack parameter, or use private webhooks.
The document is not visible yetCreation is asynchronous.Retry GET /documents/{documentId} after a short wait.
Documents created by a webhook disappearThe webhook, or the site, has a time to live.Check the webhook's ttl and the site configuration.

API Reference​