Webhooks

Receive an event when something in your book of business needs attention, instead of polling for it.

Kick pushes events to an HTTPS endpoint you own. Delivery runs on Svix, which signs every request, retries failures on a fixed schedule, and hosts the portal where you register endpoints and inspect deliveries.

Endpoints belong to the organization rather than to a workspace, so a single endpoint covers every workspace in your book of business.

Webhooks are enabled with the rest of the Platform API, per organization. If your organization does not have access yet, email [e-mail].

Register an endpoint

An organization admin registers endpoints from the same page that holds the platform token:

1. In your organization, click API in the left navigation.
2. Under Webhooks, click Open portal.
3. Add an endpoint and paste the HTTPS URL that will receive the events.
4. Subscribe the endpoint to the event types you want. Leaving the selection empty subscribes it to all of them.
5. Copy the endpoint's signing secret. It starts with whsec_ and is the key you verify deliveries with.

The portal is also where you inspect delivery logs, retry a single message, and replay failed events.

Event types

Each event has its own page holding the payload it carries and the conditions it fires under:

Event	Sent when
plaid.connection.disconnected	A Plaid connection of one of your business entities stopped syncing and has to be reconnected by the business owner

---

The event envelope

Every event arrives in the same envelope, with the fields specific to it under payload:

{
  "event": "plaid.connection.disconnected",
  "version": 1,
  "occurredAt": 1723363200,
  "payload": {}
}

Field	Type	Notes
event	string	The event type. Switch on it to route the delivery, rather than inferring the type from the endpoint it arrived on
version	integer	Version of the envelope and the payloads it carries, shared by every event type. It is raised when the shape changes in a way that could break a handler, so pin your parsing to the version you built against
occurredAt	integer	Unix time in seconds, not the ISO 8601 timestamp the REST endpoints return
payload	object	The event's own data, documented on the event's page

Because the body names its own event type, one endpoint subscribed to everything can serve your whole integration. Ids inside payload are the same uuids the REST API uses, so a workspaceId, entityId, or resource id can be passed straight to the endpoints in the reference.

---

Verify the signature

Every delivery carries three headers:

Header	Holds
svix-id	Message id, the same value across every retry of one message
svix-timestamp	Unix time in seconds at which the attempt was signed
svix-signature	Space delimited list of base64 signatures, one per active secret

The signature is a base64 HMAC-SHA256 of {svix-id}.{svix-timestamp}.{body}, keyed on the base64 decoded part of the signing secret after the whsec_ prefix. Check it against the raw request body: parsing the JSON and serializing it again changes the bytes and breaks verification.

The Svix libraries do all of that, including rejecting a delivery whose timestamp is more than five minutes out, which is what stops a captured request from being replayed at you:

import express from "express";
import { Webhook } from "svix";

const app = express();
const wh = new Webhook(process.env.KICK_WEBHOOK_SECRET);

app.post(
  "/kick/webhooks",
  express.raw({ type: "application/json" }),
  (req, res) => {
    let event;

    try {
      event = wh.verify(req.body, req.headers);
    } catch {
      return res.sendStatus(400);
    }

    switch (event.event) {
      case "plaid.connection.disconnected":
        queueReconnectReminder(event.payload);
        break;
    }

    res.sendStatus(204);
  },
);

The headers reach some receivers with a webhook- prefix instead of svix-. The official libraries accept either, so verify with one rather than reading a single prefix by hand.

Delivery and retries

Answer with any 2xx within 15 seconds. Everything else, including a 3xx redirect and a timeout, counts as a failure and is retried immediately, then after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, and 10 hours again. After the last attempt the message is marked failed, and you recover it from the portal.

An endpoint that keeps failing for five days is disabled, so check the delivery logs if events stop arriving.

Retries reuse the same svix-id, which makes it the idempotency key for your handler. Acknowledge the delivery first and do the work afterwards when processing can outrun the 15 second window.

---

Next steps

→ plaid.connection.disconnected