Webhooks

When WiseYield delivers a webhook to your application, it is signed using the Standard Webhooks specification (the same scheme used by Svix, Resend, Dodo Payments, and Clerk). This guide shows you how to verify the signature and what to expect in the payload.

Outbound webhooks are part of the versioned API expansion roadmap. The signature contract documented here is what integrators should align against today so the wire format does not change at GA.

The contract

WiseYield sends three headers with every webhook delivery:

Header	Format	Purpose
`webhook-id`	UUID	Stable identifier for this delivery (for idempotency)
`webhook-timestamp`	Unix seconds	When the webhook was signed (reject if too old)
`webhook-signature`	`v1,<base64-signature>` (space-separated for multiple)	HMAC-SHA256 of `{id}.{timestamp}.{body}` using your endpoint secret

The body is JSON:

{
  "type": "farm.created",
  "id": "evt_...",
  "timestamp": "2026-05-17T14:23:01.000Z",
  "data": { /* event-specific */ }
}

Header fallback (Svix parity)

WiseYield reads webhook-* first and falls back to svix-* on the way in, and emits both header sets on the way out for downstream compatibility. Your handler should do the same:

const id =
  req.headers['webhook-id'] ?? req.headers['svix-id'];
const timestamp =
  req.headers['webhook-timestamp'] ?? req.headers['svix-timestamp'];
const signature =
  req.headers['webhook-signature'] ?? req.headers['svix-signature'];

id = req.headers.get('webhook-id') or req.headers.get('svix-id')
timestamp = req.headers.get('webhook-timestamp') or req.headers.get('svix-timestamp')
signature = req.headers.get('webhook-signature') or req.headers.get('svix-signature')

Verifying the signature

The canonical approach is to use the official standardwebhooks (or svix) library — it handles timing-safe comparison, multi-signature parsing, and replay-window validation correctly.

import { Webhook } from 'standardwebhooks';

const wh = new Webhook(process.env.WISEYIELD_WEBHOOK_SECRET);

app.post('/webhooks/wiseyield', express.raw({ type: 'application/json' }), (req, res) => {
  const headers = {
    'webhook-id': req.headers['webhook-id'] ?? req.headers['svix-id'],
    'webhook-timestamp': req.headers['webhook-timestamp'] ?? req.headers['svix-timestamp'],
    'webhook-signature': req.headers['webhook-signature'] ?? req.headers['svix-signature'],
  };

  let event;
  try {
    event = wh.verify(req.body, headers);
  } catch (err) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // event is the parsed, verified JSON payload
  processEvent(event);
  res.status(200).end();
});

from standardwebhooks import Webhook
from flask import Flask, request, jsonify
import os

app = Flask(__name__)
wh = Webhook(os.environ['WISEYIELD_WEBHOOK_SECRET'])

@app.post('/webhooks/wiseyield')
def handle_webhook():
    headers = {
        'webhook-id': request.headers.get('webhook-id') or request.headers.get('svix-id'),
        'webhook-timestamp': request.headers.get('webhook-timestamp') or request.headers.get('svix-timestamp'),
        'webhook-signature': request.headers.get('webhook-signature') or request.headers.get('svix-signature'),
    }
    try:
        event = wh.verify(request.data, headers)
    except Exception:
        return jsonify({'error': 'Invalid signature'}), 401

    process_event(event)
    return '', 200

Why raw body matters

The signature is computed over the raw request body bytes, not the JSON-parsed object. Most web frameworks parse JSON by default — you must read the raw body before parsing, or signature verification will fail intermittently when whitespace or key ordering differs.

Express: use express.raw({ type: 'application/json' }) on the webhook route.
Next.js App Router: use request.text() before JSON.parse().
Flask: use request.data (not request.json).
FastAPI: use await request.body().

Idempotency

Webhooks can be delivered more than once — retries on network blips, processing failures on your end, etc. Use webhook-id as the dedupe key:

async function processEvent(event, webhookId) {
  const seen = await db.webhookDeliveries.upsert({
    where: { id: webhookId },
    update: {},
    create: { id: webhookId, receivedAt: new Date() },
  });
  if (seen.processedAt) {
    return; // Already handled
  }
  await doTheActualWork(event);
  await db.webhookDeliveries.update({
    where: { id: webhookId },
    data: { processedAt: new Date() },
  });
}

A unique constraint on webhook_id plus ON CONFLICT DO NOTHING is the simplest form. WiseYield uses exactly this pattern internally for the webhooks it consumes.

Replay window

webhook-timestamp is signed alongside the body. Reject deliveries older than ~5 minutes to prevent replay attacks:

const ageSeconds = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10);
if (Math.abs(ageSeconds) > 300) {
  return res.status(401).json({ error: 'Replay window exceeded' });
}

The official standardwebhooks and svix libraries enforce this automatically.

Retry behavior

When your endpoint returns a non-2xx response (or fails to respond within 30 seconds), WiseYield retries with exponential backoff:

Attempt	Delay
1	Immediate
2	5 seconds
3	30 seconds
4	5 minutes
5	30 minutes
6	2 hours
7	5 hours
8	10 hours
9	24 hours

After 9 failed attempts, the delivery is marked permanently failed and surfaced in your webhook dashboard. Return 200 as soon as you’ve verified the signature and queued the event for processing; do any heavy work asynchronously.

What to log on verification failure

When verification fails, log loudly enough to diagnose:

logger.warn('WiseYield webhook signature verification failed', {
  webhookId: req.headers['webhook-id'] ?? req.headers['svix-id'],
  seenHeaders: {
    'webhook-id': req.headers['webhook-id'],
    'svix-id': req.headers['svix-id'],
    'webhook-timestamp': req.headers['webhook-timestamp'],
    'svix-timestamp': req.headers['svix-timestamp'],
  },
  bodyLength: req.body.length,
});

The most common causes of legitimate-signature-but-failing-verification:

Body was JSON-parsed before signature check (always read raw bytes first).
Wrong endpoint secret (rotate, store in env, never commit).
Reverse-proxy stripping or re-casing headers (check for Webhook-Id vs webhook-id).
Reading the wrong header set (you sent svix-*, your code only looks for webhook-*, or vice versa).

Get Started

Guides

The contract

Header fallback (Svix parity)

Verifying the signature

Why raw body matters

Idempotency

Replay window

Retry behavior

What to log on verification failure

See also

​The contract

​Header fallback (Svix parity)

​Verifying the signature

​Why raw body matters

​Idempotency

​Replay window

​Retry behavior

​What to log on verification failure

​See also

The contract

Header fallback (Svix parity)

Verifying the signature

Why raw body matters

Idempotency

Replay window

Retry behavior

What to log on verification failure

See also