Overview

Webhooks let you receive real-time notifications when things happen in Orchpad. Instead of polling the API, Orchpad sends an HTTP POST to your endpoint when an event occurs.

Registering a webhook

Go to Settings → Webhooks → Add endpoint. Enter your URL and select which events to subscribe to.

Event types

Payload shape

Every webhook POST has the same envelope:

{
  "event": "deployment.live",
  "created_at": "2026-05-29T12:34:00Z",
  "data": {
    "project_id": "proj_abc123",
    "project_name": "My Project",
    "url": "https://my-project.orchpad.app"
  }
}

The data object shape varies by event type but always includes project_id and project_name.

Verifying signatures

Every webhook request includes an X-Orchpad-Signature header. Use it to verify the request came from Orchpad.

The signature is an HMAC-SHA256 of the raw request body, using your webhook secret as the key.

import crypto from "crypto";

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Your webhook secret is shown once when you create the endpoint. Store it securely as an environment variable.

Retries

If your endpoint returns a non-2xx status, Orchpad retries the webhook up to 5 times with exponential backoff (1m, 5m, 30m, 2h, 8h). After 5 failures the webhook is marked as failed and no further retries are attempted.

Respond quickly

Your endpoint must respond within 10 seconds. If it doesn't, Orchpad treats the delivery as failed and retries. Do any heavy processing asynchronously after returning a 200.