Webhooks

Webhooks are the alternative to polling. Subscribe an HTTPS URL on your side to one or more event topics; we’ll POST a signed JSON payload every time something matters. Use them to rebuild a static site, fan out to Slack/Discord, sync orders to your warehouse, or refresh a CDN cache.

Setup in 60 seconds

Stand up an endpoint

Any HTTPS URL that responds 2xx within 10 seconds. Keep it cheap; do the heavy work asynchronously after acknowledging.

// app/api/neural-draft/route.ts (Next.js App Router)
import { NextResponse } from "next/server";
import { verifyNeuralDraftSignature } from "@/lib/neural-draft";

export async function POST(req: Request) {
  const raw = await req.text();
  const signature = req.headers.get("x-neural-draft-signature") ?? "";
  const ok = verifyNeuralDraftSignature(raw, signature, process.env.NEURAL_DRAFT_WEBHOOK_SECRET!);
  if (!ok) return new NextResponse("invalid signature", { status: 401 });

  const event = JSON.parse(raw);
  // Acknowledge fast, do work async.
  queueMicrotask(() => handleEvent(event));
  return NextResponse.json({ received: true });
}

Create the endpoint via API or dashboard. The response includes a signing_secret — store it; it’s shown only once.

curl -X POST https://api.neuraldraft.io/v1/webhook-endpoints \
  -H "Authorization: Bearer $NEURALDRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/api/neural-draft",
    "events": ["order.paid", "order.refunded", "blog_post.published"]
  }'

{
  "id": "whe_2NgcaXxFqLPo",
  "url": "https://example.com/api/neural-draft",
  "events": ["order.paid", "order.refunded", "blog_post.published"],
  "is_active": true,
  "signing_secret": "whsec_OmtQ9X5gTzUv7sR1kBhJnAeYpV2cDfWiM3oP",
  "created_at": "2026-04-19T10:14:22Z"
}

Verify and act

On every delivery, recompute the HMAC and compare it constant-time. Reject requests with a stale timestamp (we recommend a 5-minute window).

Event topics

Topic	Fires when
`blog_post.published`	A post transitions to `status=published`, manually or via scheduler.
`blog_post.translated`	A post translation finishes (per language).
`social_post.published`	A scheduled or on-demand publish succeeded on at least one platform.
`social_post.failed`	All platforms in a post returned an error.
`order.created`	A new `Order` row is created (manual or Stripe Checkout).
`order.paid`	An `Order` transitions to `payment_status=paid`.
`order.fulfilled`	An `Order` transitions to `status=delivered`.
`order.cancelled`	An `Order` transitions to `status=cancelled`.
`order.refunded`	A full or partial refund completes.
`booking.confirmed`	A booking is confirmed (auto or manual).
`booking.cancelled`	A booking is cancelled (admin or customer).
`booking.completed`	A booking is marked complete after the appointment.
`content.changed`	A translation key value changes — useful for SSG rebuild triggers.
`image.generated`	Legacy: AI image generation is retired, so this no longer fires.
`connect.account_updated`	Stripe Connect status changes (onboarding, requirements).

A complete reference with payload schemas is on the API reference.

Delivery shape

POST /api/neural-draft HTTP/2
Host: example.com
Content-Type: application/json
User-Agent: Neural-Draft-Webhooks/1.0
X-Neural-Draft-Event: order.paid
X-Neural-Draft-Delivery: whd_2Nh4PqRsTuVw
X-Neural-Draft-Signature: t=1745007660,v1=4f3c1e8b6a... (hex)

{
  "id": "evt_2Nh4PqRsTuVw",
  "type": "order.paid",
  "created": 1745007660,
  "data": { /* same shape as the GET resource */ }
}

Verifying the signature

The signature is a hex-encoded HMAC-SHA256 of the raw body (do not parse and re-stringify) using your signing_secret. The header is t=<unix>,v1=<hex>; future signature versions will append additional algorithms (e.g. v2=).

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyNeuralDraftSignature(
  body: string,
  header: string,
  secret: string,
  toleranceSeconds = 300
): boolean {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=") as [string, string])
  );
  const t = Number(parts.t);
  const v1 = parts.v1;
  if (!Number.isFinite(t) || !v1) return false;

  // Reject ancient deliveries — protects against replay.
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - t) > toleranceSeconds) return false;

  const signed = `${t}.${body}`;
  const expected = createHmac("sha256", secret).update(signed).digest("hex");

  // Constant-time compare; both sides must be the same length.
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(v1, "hex");
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

import hmac, hashlib, time

def verify_neural_draft_signature(
    body: bytes, header: str, secret: str, tolerance_seconds: int = 300
) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    try:
        t = int(parts["t"])
        v1 = parts["v1"]
    except (KeyError, ValueError):
        return False

    if abs(int(time.time()) - t) > tolerance_seconds:
        return False

    signed = f"{t}.{body.decode('utf-8')}".encode()
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

<?php
function verifyNeuralDraftSignature(
    string $body,
    string $header,
    string $secret,
    int $toleranceSeconds = 300
): bool {
    $parts = [];
    foreach (explode(',', $header) as $kv) {
        [$k, $v] = array_pad(explode('=', $kv, 2), 2, null);
        $parts[$k] = $v;
    }

    $t = isset($parts['t']) ? (int) $parts['t'] : 0;
    $v1 = $parts['v1'] ?? '';
    if (!$t || !$v1) {
        return false;
    }

    if (abs(time() - $t) > $toleranceSeconds) {
        return false;
    }

    $signed = $t . '.' . $body;
    $expected = hash_hmac('sha256', $signed, $secret);

    return hash_equals($expected, $v1);
}

Always verify against the raw request body — if you parse JSON first and re-serialize, key ordering changes will break the HMAC. In Express, that means express.raw() on the route, not express.json(). In Next.js App Router, use await req.text() (not await req.json()).

Retry behavior

Each attempt waits up to 10 seconds for a 2xx. A 4xx answer marks the delivery failed straight away (fix your endpoint, then retry it). A 5xx, timeout or network error is retried, up to 5 attempts in total:

Attempt	Delay since previous
1	(immediate)
2	30 seconds
3	2 minutes
4	10 minutes
5	1 hour

Failed deliveries are listed with GET /v1/webhook-deliveries (and in the admin under Settings → For developers → Webhooks). Retry one by hand:

curl -X POST https://api.neuraldraft.io/v1/webhook-deliveries/{id}/retry \
  -H "Authorization: Bearer $NEURALDRAFT_API_KEY"

The data payload is the resource as it stood when the event happened.

Best practices

Acknowledge fast, work async

Return 2xx as soon as you’ve persisted the raw payload (or queued a job). Don’t run business logic in the request handler — anything over a few seconds risks a retry that double-processes.

Idempotent processing

Treat X-Neural-Draft-Delivery as the dedupe key. Index it; reject (and 2xx) duplicates. Retries happen — they’re a feature, not a bug.

Replay protection

Reject deliveries with timestamps more than 5 minutes off. The verifier helpers above do this for you.

Rotate secrets

Rotate the signing secret with POST /v1/webhook-endpoints/{id}/rotate-secret if you suspect a leak. The new secret is returned once and applies to the next delivery, so deploy it promptly.

Monitor failures

Watch the last_delivery_status field on the endpoint resource (also visible in the dashboard’s delivery log). A failed state for more than an hour is your cue to investigate.

Use one endpoint per concern

A single endpoint subscribed to many topics is fine; the X-Neural-Draft-Event header tells you which one. But splitting concerns by URL (orders, content, bookings) makes failure isolation cleaner.

Local development

Use ngrok or Cloudflare Tunnel to expose localhost, subscribe that URL, and use Send test event in the admin (Settings → For developers → Webhooks) to fire a signed sample.

Cost

Webhook deliveries use no credits.

Get started

Build with AI

Sites

Agencies

Features

SDK and API

Snippets

Setup in 60 seconds

Event topics

Delivery shape

Verifying the signature

Retry behavior

Best practices

Local development

Cost

​Setup in 60 seconds

​Event topics

​Delivery shape

​Verifying the signature

​Retry behavior

​Best practices

​Local development

​Cost

Setup in 60 seconds

Event topics

Delivery shape

Verifying the signature

Retry behavior

Best practices

Local development

Cost