Webhooks
Kontakt does not offer self-serve outbound webhook subscriptions today. This page covers what you can use instead, and how inbound webhook sources work from a developer's point of view.
Outbound webhooks
You can't yet register a URL in Kontakt and subscribe it to event types such as message delivery or consent changes. There is no webhook endpoint setting in the app or the API.
To send data from Kontakt to your systems today:
- API Call journey step. Put an API Call step in a journey at the moment you care about, such as after a message is sent, a reward is given, or a person enters an audience. The step can sign the body with HMAC SHA-256 so your endpoint can verify it came from Kontakt. See The API Call journey step.
- Customer.io connection. If you use Customer.io, Kontakt can send WhatsApp opt-outs, replies, and template delivery to it as events. See Customer.io.
- Generic Webhook fulfillment provider. For rewards, Kontakt can post each disbursement to your endpoint. See Fulfillment providers.
- Custom API tools. AI agents can call your API during conversations. See Custom API tools.
If you need event subscriptions for your integration, contact support@usekontakt.com and describe the events you need.
Receive signed requests from an API Call step
Set Sign the request to HMAC SHA-256 of the body on the step and enter a shared secret. Kontakt computes the HMAC of the exact request body with that secret and sends it in the header you chose, X-Signature by default, with the prefix you set, such as sha256=.
Your endpoint should:
- Read the raw request body before parsing it.
- Compute the HMAC SHA-256 of the raw body with the shared secret, in the encoding you chose (
hexorbase64). - Compare it with the header value, after removing the prefix, using a constant-time comparison.
- Reject the request if they differ.
Node.js example for hex encoding with a sha256= prefix:
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.KONTAKT_SIGNING_SECRET;
app.post("/kontakt", express.raw({ type: "application/json" }), (req, res) => {
const header = String(req.get("X-Signature") || "").replace(/^sha256=/, "");
const expected = crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
const valid =
header.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
if (!valid) return res.status(401).end();
const payload = JSON.parse(req.body.toString("utf8"));
// handle payload
res.status(200).json({ ok: true });
});
Kontakt does not add a timestamp to the signature, so use an ID in the body, such as {{customer.id}} together with the journey and step, if you need to ignore repeats.
Retries and timeouts
The step waits up to its Timeout (ms), at most 30 seconds. With Retry on Failure on, it retries timeouts, network errors, 429, and 5xx responses up to 5 attempts in total, doubling the wait each time. 4xx responses are not retried. Return 2xx quickly and do slow work after responding.
Inbound webhooks: webhook sources
Webhook sources accept JSON from any system and record a customer event. Setup is covered in Webhook sources. The technical contract:
Endpoint
POST https://api.usekontakt.com/webhooks/in/<workspace-id>/<slug>
Content-Type: application/json
Copy the full URL from the source's Connect tab under Settings / Webhook sources. No API key is needed.
Request
- Up to 1 MB of JSON. Other content types are read as an empty body.
- The person is found from the field at the source's dot path. Mapped event properties are read from their own paths.
- With a signing secret set, send
X-Kontakt-Signature: <hex HMAC-SHA256 of the raw body, keyed with the secret>. Asha256=prefix is accepted.
Response
| Situation | Status | Body |
|---|---|---|
| Recorded, or the source is switched off | 200 | {"data": {"ok": true}, "meta": {...}} |
| Exact same body already received | 200 | {"data": {"ok": true, "duplicate": true}, "meta": {...}} |
| Person not found and couldn't be created | 200 | {"data": {"ok": false, "error": "customer_not_resolved"}, "meta": {...}} |
| Signing secret set and the signature is missing or wrong | 401 | {"error": "bad_signature"} |
| Unknown workspace or slug, or a deleted source | 404 | Standard error body, code NOT_FOUND |
| Invalid JSON | 400 | Standard error body, code INVALID_JSON |
| Over 1 MB | 413 | Standard error body, code PAYLOAD_TOO_LARGE |
Deduplication. Kontakt hashes the raw body per source. A body it has already seen, including one that failed, returns duplicate: true and is not processed again. Include a unique delivery ID in each payload so genuine repeats of the same data are still recorded.
Security. Without a signing secret, anyone with the URL can post to it. Add one on the source's Connect tab so only signed posts are accepted. Kontakt shows the secret once; New secret replaces it immediately. To move to a new URL, change the slug on the Mapping tab; the old URL then returns 404.
When to use the API instead
Use POST /v1/events instead of a webhook source when you need profile traits, your own timestamps, idempotency keys, or several identifiers per person.