Skip to content

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:

  1. Read the raw request body before parsing it.
  2. Compute the HMAC SHA-256 of the raw body with the shared secret, in the encoding you chose (hex or base64).
  3. Compare it with the header value, after removing the prefix, using a constant-time comparison.
  4. 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>. A sha256= prefix is accepted.

Response

SituationStatusBody
Recorded, or the source is switched off200{"data": {"ok": true}, "meta": {...}}
Exact same body already received200{"data": {"ok": true, "duplicate": true}, "meta": {...}}
Person not found and couldn't be created200{"data": {"ok": false, "error": "customer_not_resolved"}, "meta": {...}}
Signing secret set and the signature is missing or wrong401{"error": "bad_signature"}
Unknown workspace or slug, or a deleted source404Standard error body, code NOT_FOUND
Invalid JSON400Standard error body, code INVALID_JSON
Over 1 MB413Standard 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.