Webhook triggers

A webhook trigger gives a published workflow a private URL that another service can POST JSON to, for example a CRM's “lead created” webhook or a help desk's “ticket created” webhook. Add one in the Studio from the workflow's API dialog, under Webhook trigger. A workflow can have up to 5 triggers.

The URL

POST https://kovca.io/api/v1/hooks/kvh_...
Content-Type: application/json

• The URL contains a random 256-bit token. Kovca stores only its hash, so the full URL is shown once. Create a new URL at any time; the old one stops working immediately.
• Unknown, deleted, and turned-off triggers all answer 404 NOT_FOUND.
• A trigger runs the latest published version, or a version you pin. A turned-off workflow answers 403 WORKFLOW_DISABLED.

Verification

The URL is a credential. To also prove that requests come from the sender, require one of:

• Shared secret header: the sender puts a secret you choose in a header.
• HMAC signature: the sender signs the raw body with a shared secret (SHA-256, SHA-512, or SHA-1; hex or base64; an optional prefix like sha256=; and optionally a timestamp header, in which case {timestamp}.{body} is signed and requests older than 5 minutes are refused).
• Standard Webhooks: webhook-id, webhook-timestamp, and webhook-signature with a whsec_ secret.

A request that fails verification gets 401 TRIGGER_SIGNATURE_INVALID and nothing runs. Secrets are encrypted and never shown again.

Mapping the payload

By default the request body is the workflow input. Or map fields one by one: each workflow input field takes a value from body.<path> (for example body.lead.email or body.items[0].sku), headers.<name>, query.<name>, or a fixed value. Fields whose source is missing are left out. Authorization, Cookie, and the signature header are never available to mappings. The Studio previews the mapped input for a sample payload in your browser.

Responses

Kovca checks the input against the workflow, the rate limit, and your plan's quota before answering. Problems come back right away (400, 429, 402), so the sender can retry. Otherwise the answer is 202 Accepted, and the run continues in the background with the same 30-second limit:

{
  "request_id": "req_...",
  "run_id": "run_...",
  "status": "accepted"
}

Follow the run in Executions (source “Webhook trigger”), with GET /v1/runs/{id} and an API key, or get its outcome pushed to you with an outbound webhook. Trigger runs are billed exactly like API calls: one evaluation per successful intelligence step.

Duplicate deliveries

Senders retry. Set a de-duplication header (for example webhook-id or X-GitHub-Delivery): a request whose value matches one from the last 24 hours, with the same payload, returns 202 with the original run instead of running again. The same value with a different payload returns 409 IDEMPOTENCY_KEY_CONFLICT. See Idempotency.