Webhooks

Subscribe to events to react to things happening inside your Jewel Value account.

Registering

POST /api/v1/webhooks

{
  "url": "https://your-app.example.com/webhooks/jewelvalue",
  "events": ["valuation.created", "valuation.updated", "certificate.generated"]
}

Available events

• valuation.created — new valuation saved
• valuation.updated — any field on a valuation changed
• valuation.cancelled — soft-deleted
• certificate.generated — PDF rendered and stored
• certificate.failed — generation failed after all retries
• customer.created, customer.updated

Payload

Every event POSTs JSON of the form:

{
  "id": "evt_…",
  "event": "valuation.created",
  "occurredAt": "2026-04-25T18:00:00Z",
  "tenantId": "…",
  "data": { /* the resource */ }
}

Signature verification

Each request carries an X-JewelValue-Signature header — HMAC-SHA256 of the raw body using your webhook secret (shown once when you create the webhook).

const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) reject();

Retries

We retry on non-2xx responses with exponential backoff for up to 24 hours. After that the delivery is marked permanently failed and visible in Settings > Integrations > Webhook Deliveries.

Replay

Failed deliveries can be replayed manually from the same page.