Skip to main content

Receive a webhook

Deliver an event to a webhook configured for a workflow.

POST /webhooks/:webhookId

Paths are relative to the public API base URL. Prefer the complete URL copied from Settings → Webhook Triggers, for example:

https://app.intellectible.com/api/publicv1/webhooks/YOUR_WEBHOOK_ID

webhookId is Intellectible’s endpoint ID, not a project ID, workflow ID, or the sender’s delivery ID.

Request​

Send Content-Type: application/json and a valid JSON body of at most 1 MiB. Your payload structure is application-defined; Intellectible passes the parsed body to the workflow as payload.

Authenticate with the method configured on this webhook. A project API key in Authorization does not replace webhook authentication.

The examples below trigger a real workflow when run against an active endpoint. Use a workflow with safe test actions first.

Generic static token​

Set INTELLECTIBLE_WEBHOOK_URL to the copied URL and load the generated token securely into INTELLECTIBLE_WEBHOOK_SECRET. Keep it out of source control and shell history.

curl --include --request POST \
--header "Content-Type: application/json" \
--header "X-Webhook-Token: ${INTELLECTIBLE_WEBHOOK_SECRET}" \
--data '{"event":"record.created","recordId":"record-123"}' \
"${INTELLECTIBLE_WEBHOOK_URL}"

The token is compared with the configured secret. It does not sign the body and does not enable automatic duplicate detection.

Generic HMAC​

Configure the signing secret in the webhook settings before sending requests. Until setup is complete, the endpoint returns 409 SETUP_REQUIRED.

HeaderRequired value
Webhook-IdSender’s unique event/delivery ID. Reuse it for retries of the same event.
Webhook-TimestampPositive integer Unix time in seconds, within five minutes of the server’s time.
Webhook-Signaturev1= followed by the 64-character hexadecimal HMAC-SHA256 digest.

Sign this exact byte sequence, including the two periods:

<Webhook-Id>.<Webhook-Timestamp>.<raw request body>

Use the complete secret string as the HMAC key. Do not remove a prefix or Base64-decode it. Sign the exact UTF-8 body that you send; changing whitespace or serializing JSON again can change the signature.

Example custom sender, using Node.js with built-in fetch:

import { createHmac, randomUUID } from 'node:crypto';

const endpoint = process.env.INTELLECTIBLE_WEBHOOK_URL;
const secret = process.env.INTELLECTIBLE_WEBHOOK_SIGNING_SECRET;
if (!endpoint || !secret) throw new Error('Set the webhook URL and signing secret.');

// Persist this ID with the event; reuse it only for retries of this event.
const deliveryId = randomUUID();
const timestamp = String(Math.floor(Date.now() / 1000));
const body = JSON.stringify({ event: 'record.created', recordId: 'record-123' });
const signature = createHmac('sha256', secret)
.update(`${deliveryId}.${timestamp}.`)
.update(body)
.digest('hex');

const response = await fetch(endpoint, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Webhook-Id': deliveryId,
'Webhook-Timestamp': timestamp,
'Webhook-Signature': `v1=${signature}`,
},
body,
});

const result = await response.text();
if (!response.ok) throw new Error(`Webhook rejected (${response.status}): ${result}`);
console.log('Delivery accepted:', result);

Keep the sender’s clock synchronized. On retries, retain the event’s delivery ID and body but calculate a fresh timestamp and signature. Running this entire example again generates a new delivery ID, so it is treated as a new event.

Typeform signature​

For a webhook whose source is Typeform, use:

Typeform-Signature: sha256=BASE64_DIGEST

The digest is Base64(HMAC-SHA256(secret, rawBody)), using the secret generated when the webhook was created. Unlike Generic HMAC, this format signs only the exact raw body, uses Base64 instead of hexadecimal, and has no timestamp header.

Configure the URL and secret in Typeform and send its normal payload. The submission’s form_response.token, when present, is used for duplicate detection.

Workflow inputs​

An accepted request supplies inputs like:

{
"payload": {
"event": "record.created",
"recordId": "record-123"
},
"webhook": {
"source": "generic",
"webhookId": "YOUR_WEBHOOK_ID",
"receivedAt": "2026-10-30T12:00:00.000Z",
"headers": {
"content-type": "application/json"
}
}
}

source is generic for both generic authentication modes, or typeform. receivedAt is an ISO timestamp. The headers shown are an excerpt; other non-filtered request headers can also be present.

Before passing headers to the workflow, Intellectible removes Authorization, Cookie, X-API-Key, X-Auth-Token, X-Webhook-Token, Webhook-Signature, and Proxy-Authorization. This is not blanket redaction of custom headers or payload values. Do not include secrets in other fields or log sensitive inputs.

Success response​

200 OK

{
"ok": true
}

This means the workflow was accepted for execution, or this delivery was already accepted. The response does not distinguish duplicates and does not include a run ID, workflow output, or execution result. Check workflow API logs for the outcome.

See Retries and duplicate deliveries for the 24-hour deduplication window and retry guidance.

Error responses​

Webhook errors normally contain error and message, for example:

{
"error": "UNAUTHENTICATED",
"message": "Missing X-Webhook-Token header"
}
HTTP statusError codeAction
400Request-parser errorSend valid JSON. The body may use a different error format.
401UNAUTHENTICATEDCheck the token or signature, signing mode, exact body, and HMAC timestamp.
404NOT_FOUNDCheck the endpoint ID and whether the webhook was deleted.
409SETUP_REQUIREDSave the HMAC signing secret in workflow settings.
410DISABLEDEnable the webhook in settings.
410GONEThe destination workflow no longer exists.
413PAYLOAD_TOO_LARGEReduce the body to at most 1 MiB.
429RATE_QUOTA_EXCEEDED or CONCURRENT_QUOTA_EXCEEDEDBack off; an ingress or execution limit was reached.
503DELIVERY_PENDINGThe same delivery is still being admitted. Retry after the supplied Retry-After: 2.
503SERVICE_UNAVAILABLERetry with backoff; a required service is temporarily unavailable.
500WORKFLOW_START_FAILED, SECRET_ERROR, or INTERNAL_ERRORInspect the message; investigate persistent failures.

Handle non-JSON failures from request parsing or upstream infrastructure too. A lost response leaves acceptance uncertain, so use stable delivery IDs and idempotent workflow actions rather than blindly creating a new event for each retry.