Webhooks Guide

This guide walks through building a production-grade webhook receiver for Cresora events. For the full event catalog, see Event types.

1. Register your endpoint

In the Partner Portal → API Settings → Webhooks → Add Endpoint. Enter your public HTTPS URL and copy the signing secret.

2. Implement the receiver

Your endpoint must:

• Accept POST requests with Content-Type: application/json
• Return 2xx within 30 seconds
• Verify the HMAC-SHA256 signature before processing

See Signature verification for the complete verification code.

3. Handle events idempotently

Cresora retries on non-2xx responses, so your handler must be idempotent — processing the same event twice must produce the same outcome.

// Use the event ID as an idempotency key
async function handleWebhook(event) {
  const alreadyProcessed = await db.webhookEvents.findOne({ id: event.id });
  if (alreadyProcessed) return; // deduplicate

  await db.webhookEvents.insert({ id: event.id, processedAt: new Date() });
  await processEvent(event);
}

4. Respond quickly, process async

Return 200 OK as fast as possible, then process the event in a background job:

app.post("/webhooks/cresora", (req, res) => {
  verifySignature(req); // throws on invalid signature
  res.sendStatus(200);  // respond immediately
  queue.enqueue(req.body); // process asynchronously
});

Retry schedule

Testing locally

Use ngrok or any tunnel service to expose localhost, then register the tunnel URL in the Portal. See Testing webhooks →.