Webhooks

Webhooks send a notification after a Planck request completes. Use them to score responses, feed an analytics pipeline, or trigger another workflow.

Delivery model

Planck uses a durable PostgreSQL outbox and delivers webhooks asynchronously. A successful gateway request does not wait for your webhook endpoint.

Delivery is at least once. Deduplicate with Planck-Delivery-Id.
A delivery is retried for timeouts, HTTP 408, 425, 429, and 5xx responses.
Redirects are not followed. Configure the final HTTPS endpoint directly.
Other 4xx responses are treated as permanent failures.
Each delivery attempt can run for up to two minutes.

Return a 2xx response quickly after durably accepting the event, then do slow work from your own queue.

Quick start

Create an HTTPS receiver

Your endpoint must accept POST requests over HTTPS. Preserve the raw request bytes so you can verify the HMAC signature before parsing JSON.

Add the webhook

Open the webhooks page, enter the endpoint, choose a sample rate, and optionally add property filters.You can also use the REST API.

Verify the signature

Copy the HMAC key shown in the dashboard. The Planck-Signature header is the hex-encoded HMAC-SHA256 of the exact HTTP body bytes.

import crypto from "node:crypto";
import express from "express";

const app = express();

app.post(
  "/webhooks/planck",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const rawBody = req.body;
    const signature = req.header("Planck-Signature") ?? "";
    const expected = crypto
      .createHmac("sha256", process.env.PLANCK_WEBHOOK_SECRET)
      .update(rawBody)
      .digest("hex");

    const valid =
      /^[0-9a-f]{64}$/i.test(signature) &&
      crypto.timingSafeEqual(
        Buffer.from(expected, "hex"),
        Buffer.from(signature, "hex")
      );

    if (!valid) return res.status(401).send("invalid signature");

    const event = JSON.parse(rawBody.toString("utf8"));
    await queueEvent({
      deliveryId: req.header("Planck-Delivery-Id"),
      event,
    });
    return res.status(202).send("accepted");
  }
);

Do not verify a re-serialized object such as JSON.stringify(req.body). Even equivalent JSON can produce different bytes and fail signature validation.

Configuration

Setting	Meaning	Default
Destination URL	Public HTTPS URL that receives deliveries	Required
Sample rate	Percentage of matching requests to send, from 0 to 100	100%
Include enhanced data	Adds model, provider, metrics, and a full-body URL when one exists	Enabled
Property filters	Sends only when every configured key/value matches	None

Property names created from Planck-Property-* headers are lowercase. For example, this request property:

Planck-Property-Environment: production

matches a webhook filter with key environment and value production.

Payload

Small request and response bodies remain inline as their original JSON values:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "user-123",
  "request_body": {
    "model": "gpt-4o-mini",
    "messages": [{ "role": "user", "content": "Hello" }]
  },
  "response_body": {
    "choices": [{ "message": { "role": "assistant", "content": "Hi" } }]
  },
  "model": "gpt-4o-mini",
  "provider": "OPENAI",
  "metadata": {
    "cost": 0.0015,
    "promptTokens": 10,
    "completionTokens": 15,
    "totalTokens": 25,
    "latencyMs": 1200
  }
}

Request and response bodies larger than 10 KB are represented by a truncation message. When enhanced data is enabled, request_response_url is also present and points to the complete S3-backed record:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "request_body": "Body too large for webhook; fetch the full request and response from request_response_url",
  "response_body": { "choices": [] },
  "request_response_url": "https://object-storage.example/..."
}

request_response_url is conditional, not present on every webhook. It is generated only when the completed interaction was externalized to S3. The URL expires after two hours by default; fetch it as soon as you accept the event.

For organizations using application-level request/response encryption, the direct object-storage URL contains ciphertext rather than readable JSON. The dashboard and MCP server use the authenticated request API to decrypt these records. Full-body webhook retrieval for encrypted records requires a separate signed decryption endpoint and is not currently available.

Storage behavior

Requests do not all go to S3. Planck stores searchable metadata and small bodies in ClickHouse. It externalizes request/response data above 10 KB and inline image assets to private object storage, while ClickHouse retains the storage reference. This keeps ordinary requests queryable without creating an object for every call and preserves a complete source for oversized webhook bodies. Use Planck-Omit-Request: true or Planck-Omit-Response: true when a body must not be retained.

Delivery headers

Header	Description
`Planck-Signature`	HMAC-SHA256 of the exact body bytes
`Planck-Delivery-Id`	Stable delivery ID to use for deduplication
`Planck-Delivery-Attempt`	One-based attempt number

The dashboard’s Test action sends a synchronous synthetic payload to check URL reachability and HMAC handling. It does not exercise the production outbox and retry worker. Follow the production canary procedure for a full-path test.

Local and production testing

Test the receiver, HMAC verification, and durable delivery path

Custom properties

Control webhook delivery with request properties

Scores

Score LLM responses for quality monitoring

User metrics

Track per-user usage patterns and costs

Need more help?

Additional questions or feedback? Reach out to help@inquantum.ai or schedule a call with us.

Getting Started

AI Gateway

Observability & Analytics

Prompt Management

Async Logging

Custom Logs

Delivery model

Quick start

Configuration

Payload

Storage behavior

Delivery headers

Local and production testing

Custom properties

Scores

User metrics

​Delivery model

​Quick start

​Configuration

​Payload

​Storage behavior

​Delivery headers

​Related features

Local and production testing

Custom properties

Scores

User metrics

Delivery model

Quick start

Configuration

Payload

Storage behavior

Delivery headers

Related features