Skip to main content
Open in ClaudeOpen in ChatGPTllms-full.txt

Webhooks

Every meaningful change on your cases is POSTed to your registered HTTPS endpoint as a signed event, with automatic retries. This page is the complete receiver contract, plus a ready-to-run receiver in six stacks.

The delivery​

POST <your-callback-url>
Content-Type:           application/json
X-Fieldproof-Event:     payment.collected           ← event type
X-Fieldproof-Delivery:  evt_66a1f0c2d3e4f5a6b7c8d9e0 ← = eventId; your dedupe key
X-Fieldproof-Timestamp: 1755475200000               ← unix milliseconds
X-Fieldproof-Signature: 3f1a…                        ← lowercase hex, HMAC-SHA256

Each delivery also carries X-Quikkred-Event / -Delivery / -Timestamp / -Signature with identical values (legacy aliases). Read the X-Fieldproof-* names and fall back to the aliases.

The body is the common event envelope — see the event reference.

Verifying the signature​

Same scheme as request signing, in reverse. We compute:

signature = lowercase_hex( HMAC-SHA256( hmacSecret,
              "POST" + "\n" + <callback path> + "\n" + <X-Fieldproof-Timestamp> + "\n" + <raw body> ) )
  • hmacSecret is the same secret you use to sign requests to us.
  • <callback path> is the pathname of the callback URL you registered — https://api.yourorg.in/webhooks/fieldproof → /webhooks/fieldproof. It is the pathname only, never a query string. Do not register a callback URL that contains a query string. If a reverse proxy strips a prefix before your app sees the request (/api/webhooks/fieldproof → /webhooks/fieldproof), sign with the public pathname, i.e. the one in the URL you registered.
  • <raw body> is the exact bytes we sent. Verify against the raw request body, never against a re-serialised copy of a parsed object (key order, spacing and number formatting would change the bytes).
  • Compare in constant time; lower-case the received header before comparing.
  • Reject timestamps more than 5 minutes from your clock (replay protection).

:::warning Accept more than one secret When you rotate your key, webhooks are signed with the new secret from the moment of rotation, while your requests are accepted with old or new until you retire the old one. So your receiver must be able to verify against a list of secrets before you request a rotation — otherwise every delivery fails until you deploy. All samples below take an array. See key lifecycle. :::

The five receiver rules​

  1. Verify the signature over the raw bytes, against your list of secrets, before trusting anything.
  2. Respond 2xx within 10 seconds. Persist the event, acknowledge, then do the work (or do a handful of SQL statements inline — see Updating your LMS). A non-2xx, a timeout, or a connection failure means "not received" and we retry.
  3. Dedupe on eventId — delivery is at-least-once; retries and replays are normal, not errors.
  4. Gate case-state on sequence per case — never gate money. Sequence is per case, gaps are normal, arrival order is not guaranteed (details). A late or out-of-order payment.collected is still booked (idempotent on eventId / reference); only your case-state fields follow the watermark.
  5. Use the absolute values in payloads (totalCollected, outstandingAfter) — never accumulate deltas yourself.

:::note The ping event The webhook self-test sends a ping whose sourceLoanNumber and sequence are null. Verify it like any event, return 2xx, apply nothing — and make sure your JSON model tolerates the nulls. :::

Ordering: the sequence field​

Every event carries an integer sequence. The rules that make it useful:

  • It is per case, not per loan. It starts at 1 for every new case. A loan whose case closed (collected / closed_unrecovered) and is later re-pushed gets a new caseId and the sequence restarts at 1. Key your watermark on (sourceLoanNumber, caseId) — or reset the watermark whenever you see case.received for that loan.
  • It counts every event type, including ones you are not subscribed to. The default subscription is case.received, payment.collected, case.closed; the case.assigned and visit.completed events in between still consume numbers. Seeing 1 → 4 → 5 is normal for a default subscriber. Never wait for a gap to fill.
  • Arrival order is not guaranteed. Retries, replays and concurrent delivery (a backlog drains with up to 25 POSTs in flight, not strictly serialised per case) mean a sequence 5 can reach you before sequence 4.
  • Rule: apply an event's case-state changes only if its sequence is greater than your watermark for that case, then move the watermark. On a gap you may reconcile with GET /api/v1/partner/cases/{sourceLoanNumber} (the authoritative snapshot) — but do it after applying, not instead of it.
  • Money is exempt from the gate. A payment.collected that arrives late or out of order is still a real payment: write it to your ledger (idempotent on eventId, and on reference where present); only the outstandingAfter / totalCollected / status fields follow the watermark.

The transactional handler that encodes all of this is on Updating your LMS from our events.

Retries, exhaustion and the circuit breaker​

  • Retry ladder: 0s → 30s → 2m → 10m → 1h → 6h → 24h — 7 attempts over ≈31 hours. After the last failure the delivery is exhausted; it stays replayable for 30 days via the delivery log.
  • Circuit breaker: after 20 consecutive failures we suspend delivery to your endpoint and probe it every 15 minutes. It recovers automatically; the backlog then drains oldest-first (up to 25 concurrent POSTs, so per-case order is not guaranteed — the sequence rules above cover it).
  • You are not paged by us. The platform does not send alerts to your technical contact for exhausted deliveries or a breaker trip. Monitor GET /api/v1/partner/webhooks/deliveries?status=exhausted (and GET /api/v1/partner/health) from your side, and use the poll API as your recovery lane after an outage.

Callback URL rules​

RuleDetail
https:// onlyPlain http callbacks are not accepted.
Public IPPrivate and loopback addresses are refused.
No query stringThe signed path is the pathname only; keep the URL clean.
No redirectsWe do not follow 3xx. A redirect is a failed attempt.
10 s timeoutConnect + response, end to end.
Response body ≤ 64 KBWe read at most 64 KB of your response; anything is fine, {} is enough.

The URL is configured per environment by our ops (CRM Integrations tab) — sandbox and production are separate registrations; nothing carries over.

Reference receivers​

All six samples do the same thing: read the raw body, verify against a list of secrets, reject a stale timestamp, tolerate ping, insert the event into your inbox (dedupe on eventId), acknowledge, and hand the event to your apply handler. Wire insertEventIfAbsent / applyFieldproofEvent to the tables on Updating your LMS.

Node / Express​

fieldproof-webhook.js (Node 18+, Express 4/5)
const express = require("express");
const crypto = require("crypto");

const app = express();

// Pathname of the callback URL you registered (no query string).
const CALLBACK_PATH = "/webhooks/fieldproof";
// Current secret first; keep the previous one during a rotation.
const SECRETS = [process.env.FIELDPROOF_SECRET_CURRENT, process.env.FIELDPROOF_SECRET_PREVIOUS].filter(Boolean);

// Wire these two to your database / job queue (see "Updating your LMS").
const store = { insertEventIfAbsent: async (eventId, event) => true }; // INSERT ... ON CONFLICT DO NOTHING → true if inserted
const queue = { push: (job) => setImmediate(job) };                    // your worker queue
async function applyFieldproofEvent(event) { /* transactional handler — see "Updating your LMS" */ }

function verifySignature(rawBody, req) {
  const ts = req.get("X-Fieldproof-Timestamp") || req.get("X-Quikkred-Timestamp");
  const sig = (req.get("X-Fieldproof-Signature") || req.get("X-Quikkred-Signature") || "").toLowerCase();
  if (!ts || !sig || !/^\d+$/.test(ts)) return false;
  if (Math.abs(Date.now() - Number(ts)) > 5 * 60 * 1000) return false;      // ±5 min replay window
  const canonical = Buffer.concat([Buffer.from(`POST\n${CALLBACK_PATH}\n${ts}\n`, "utf8"), rawBody]);
  return SECRETS.some((secret) => {
    const expected = crypto.createHmac("sha256", secret).update(canonical).digest("hex"); // lowercase hex
    return expected.length === sig.length &&
      crypto.timingSafeEqual(Buffer.from(expected, "utf8"), Buffer.from(sig, "utf8"));
  });
}

// express.raw() ON THIS ROUTE gives req.body as a Buffer of the exact bytes.
app.post(CALLBACK_PATH, express.raw({ type: "application/json", limit: "1mb" }), async (req, res) => {
  const rawBody = Buffer.isBuffer(req.body) ? req.body : req.rawBody;   // req.rawBody: see the note below
  if (!rawBody || !verifySignature(rawBody, req)) return res.status(401).end();

  const event = JSON.parse(rawBody.toString("utf8"));
  if (event.type === "ping") return res.status(200).json({ ok: true });  // sourceLoanNumber / sequence are null

  const isNew = await store.insertEventIfAbsent(event.eventId, event);   // dedupe on eventId (durable inbox)
  if (isNew) queue.push(() => applyFieldproofEvent(event));             // do the work off the request
  res.status(200).json({ received: true });                              // ack within 10 s
});

app.listen(process.env.PORT || 8080);

:::warning Already using app.use(express.json()) globally? If express.json() is mounted before this route, it consumes the request stream and req.body is a parsed object by the time express.raw() runs (it is skipped). Verifying against JSON.stringify(req.body) will fail: it is not the bytes we signed. Keep the raw bytes at parse time instead:

app.js — capture raw bytes alongside global JSON parsing
app.use(express.json({
  verify: (req, _res, buf) => { req.rawBody = buf; }, // Buffer of the exact bytes received
}));
// The route handler above already prefers Buffer req.body and falls back to req.rawBody.

:::

Python / Flask​

fieldproof_webhook.py (Flask 2+)
import hashlib, hmac, json, os, time
from flask import Flask, jsonify, request

app = Flask(__name__)

CALLBACK_PATH = "/webhooks/fieldproof"   # pathname of the URL you registered (no query string)
SECRETS = [s.encode() for s in (os.environ.get("FIELDPROOF_SECRET_CURRENT"),
                                os.environ.get("FIELDPROOF_SECRET_PREVIOUS")) if s]

# Wire these to your database / job queue (see "Updating your LMS").
def insert_event_if_absent(event_id: str, event: dict) -> bool:   # INSERT ... ON CONFLICT DO NOTHING → True if inserted
    return True
def enqueue_apply(event: dict) -> None:                           # hand to your worker; it runs apply_fieldproof_event
    pass


def verify_signature(raw_body: bytes, headers) -> bool:
    ts = headers.get("X-Fieldproof-Timestamp") or headers.get("X-Quikkred-Timestamp") or ""
    sig = (headers.get("X-Fieldproof-Signature") or headers.get("X-Quikkred-Signature") or "").lower()
    if not ts.isdigit() or not sig:
        return False
    if abs(time.time() * 1000 - int(ts)) > 5 * 60 * 1000:        # ±5 min replay window
        return False
    canonical = f"POST\n{CALLBACK_PATH}\n{ts}\n".encode() + raw_body
    return any(
        hmac.compare_digest(hmac.new(secret, canonical, hashlib.sha256).hexdigest(), sig)
        for secret in SECRETS
    )


@app.post(CALLBACK_PATH)
def fieldproof_webhook():
    raw_body = request.get_data()                # exact bytes; never re-serialise request.json
    if not verify_signature(raw_body, request.headers):
        return "", 401

    event = json.loads(raw_body)
    if event["type"] == "ping":                  # sourceLoanNumber / sequence are None
        return jsonify(ok=True)

    if insert_event_if_absent(event["eventId"], event):   # dedupe on eventId
        enqueue_apply(event)                              # apply off the request thread
    return jsonify(received=True)                          # ack within 10 s


if __name__ == "__main__":
    app.run(port=8080)

Java / Spring Boot​

FieldproofWebhookController.java (Spring Boot 3, Java 17+)
package com.example.fieldproof;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RestController;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.ArrayList;
import java.util.HexFormat;
import java.util.List;
import java.util.Locale;
import java.util.Map;

@RestController
public class FieldproofWebhookController {

  /** Pathname of the callback URL you registered — include any servlet context-path or proxy prefix. No query string. */
  private static final String CALLBACK_PATH = "/webhooks/fieldproof";
  private static final List<String> SECRETS = secretsFromEnv();      // current first; keep the previous one during rotation
  private static final ObjectMapper MAPPER = new ObjectMapper();

  // Wire these to your database / job queue (see "Updating your LMS").
  public interface EventStore { boolean insertEventIfAbsent(String eventId, byte[] rawEvent); } // INSERT ... ON CONFLICT DO NOTHING
  public interface JobQueue   { void enqueue(Runnable job); }
  public interface Lms        { void applyFieldproofEvent(byte[] rawEvent); }                  // transactional handler

  private final EventStore store;
  private final JobQueue jobs;
  private final Lms lms;

  public FieldproofWebhookController(EventStore store, JobQueue jobs, Lms lms) {
    this.store = store; this.jobs = jobs; this.lms = lms;
  }

  // @RequestBody byte[] hands you the exact bytes — no re-serialisation.
  @PostMapping(value = CALLBACK_PATH, consumes = MediaType.APPLICATION_JSON_VALUE)
  public ResponseEntity<?> receive(@RequestBody byte[] rawBody,
                                   @RequestHeader HttpHeaders headers) throws Exception {
    String ts  = first(headers, "X-Fieldproof-Timestamp", "X-Quikkred-Timestamp");
    String sig = first(headers, "X-Fieldproof-Signature", "X-Quikkred-Signature");
    if (!verify(rawBody, ts, sig)) return ResponseEntity.status(401).build();

    JsonNode event = MAPPER.readTree(rawBody);
    if ("ping".equals(event.path("type").asText())) {                 // sourceLoanNumber / sequence are null
      return ResponseEntity.ok(Map.of("ok", true));
    }
    String eventId = event.path("eventId").asText();
    if (store.insertEventIfAbsent(eventId, rawBody)) {                // dedupe on eventId
      jobs.enqueue(() -> lms.applyFieldproofEvent(rawBody));           // apply off the request thread
    }
    return ResponseEntity.ok(Map.of("received", true));               // ack within 10 s
  }

  private static boolean verify(byte[] rawBody, String ts, String sig) throws Exception {
    if (ts == null || sig == null) return false;
    long tsMs;
    try { tsMs = Long.parseLong(ts); } catch (NumberFormatException e) { return false; }
    if (Math.abs(System.currentTimeMillis() - tsMs) > 5 * 60 * 1000L) return false;   // ±5 min replay window

    byte[] prefix   = ("POST\n" + CALLBACK_PATH + "\n" + ts + "\n").getBytes(StandardCharsets.UTF_8);
    byte[] received = sig.toLowerCase(Locale.ROOT).getBytes(StandardCharsets.UTF_8);
    for (String secret : SECRETS) {
      Mac mac = Mac.getInstance("HmacSHA256");
      mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
      mac.update(prefix);
      mac.update(rawBody);
      byte[] expected = HexFormat.of().formatHex(mac.doFinal()).getBytes(StandardCharsets.UTF_8); // lowercase hex
      if (MessageDigest.isEqual(expected, received)) return true;                                // constant time
    }
    return false;
  }

  private static String first(HttpHeaders headers, String... names) {
    for (String n : names) { String v = headers.getFirst(n); if (v != null && !v.isEmpty()) return v; }
    return null;
  }

  private static List<String> secretsFromEnv() {
    List<String> out = new ArrayList<>();
    for (String k : new String[] {"FIELDPROOF_SECRET_CURRENT", "FIELDPROOF_SECRET_PREVIOUS"}) {
      String v = System.getenv(k);
      if (v != null && !v.isEmpty()) out.add(v);
    }
    return out;
  }
}

Go / net/http​

main.go (Go 1.20+)
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"crypto/subtle"
	"encoding/hex"
	"encoding/json"
	"io"
	"log"
	"net/http"
	"os"
	"strconv"
	"strings"
	"time"
)

const callbackPath = "/webhooks/fieldproof" // pathname of the URL you registered (no query string)

var secrets = loadSecrets() // current first; keep the previous one during rotation

func loadSecrets() [][]byte {
	var out [][]byte
	for _, k := range []string{"FIELDPROOF_SECRET_CURRENT", "FIELDPROOF_SECRET_PREVIOUS"} {
		if v := os.Getenv(k); v != "" {
			out = append(out, []byte(v))
		}
	}
	return out
}

// Wire these to your database / job queue (see "Updating your LMS").
func insertEventIfAbsent(eventID string, rawEvent []byte) bool { return true } // INSERT ... ON CONFLICT DO NOTHING → true if inserted
func applyFieldproofEvent(rawEvent []byte)                     {}             // transactional handler

func header(r *http.Request, names ...string) string {
	for _, n := range names {
		if v := r.Header.Get(n); v != "" {
			return v
		}
	}
	return ""
}

func verifySignature(rawBody []byte, ts, sig string) bool {
	if ts == "" || sig == "" {
		return false
	}
	tsMs, err := strconv.ParseInt(ts, 10, 64)
	if err != nil {
		return false
	}
	if d := time.Now().UnixMilli() - tsMs; d > 5*60*1000 || d < -5*60*1000 { // ±5 min replay window
		return false
	}
	received := []byte(strings.ToLower(sig))
	prefix := []byte("POST\n" + callbackPath + "\n" + ts + "\n")
	for _, secret := range secrets {
		mac := hmac.New(sha256.New, secret)
		mac.Write(prefix)
		mac.Write(rawBody)
		expected := []byte(hex.EncodeToString(mac.Sum(nil))) // lowercase hex
		if subtle.ConstantTimeCompare(expected, received) == 1 {
			return true
		}
	}
	return false
}

func fieldproofWebhook(w http.ResponseWriter, r *http.Request) {
	if r.Method != http.MethodPost {
		w.WriteHeader(http.StatusMethodNotAllowed)
		return
	}
	rawBody, err := io.ReadAll(io.LimitReader(r.Body, 1<<20)) // exact bytes
	if err != nil {
		w.WriteHeader(http.StatusBadRequest)
		return
	}
	ts := header(r, "X-Fieldproof-Timestamp", "X-Quikkred-Timestamp")
	sig := header(r, "X-Fieldproof-Signature", "X-Quikkred-Signature")
	if !verifySignature(rawBody, ts, sig) {
		w.WriteHeader(http.StatusUnauthorized)
		return
	}

	var event struct {
		EventID          string  `json:"eventId"`
		Type             string  `json:"type"`
		SourceLoanNumber *string `json:"sourceLoanNumber"` // nil on ping
		Sequence         *int64  `json:"sequence"`         // nil on ping
	}
	if err := json.Unmarshal(rawBody, &event); err != nil {
		w.WriteHeader(http.StatusBadRequest)
		return
	}
	w.Header().Set("Content-Type", "application/json")
	if event.Type == "ping" {
		w.Write([]byte(`{"ok":true}`))
		return
	}
	if insertEventIfAbsent(event.EventID, rawBody) { // dedupe on eventId
		go applyFieldproofEvent(rawBody)             // or hand to your job queue
	}
	w.Write([]byte(`{"received":true}`)) // ack within 10 s
}

func main() {
	http.HandleFunc(callbackPath, fieldproofWebhook)
	log.Fatal(http.ListenAndServe(":8080", nil))
}

C# / ASP.NET Core minimal API​

Program.cs (.NET 6+)
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

const string CallbackPath = "/webhooks/fieldproof";   // pathname of the URL you registered (no query string)
var secrets = new[] { "FIELDPROOF_SECRET_CURRENT", "FIELDPROOF_SECRET_PREVIOUS" }   // current first
    .Select(name => Environment.GetEnvironmentVariable(name))
    .Where(s => !string.IsNullOrEmpty(s))
    .Select(s => s!)
    .ToArray();

static string? Header(HttpRequest req, params string[] names)
{
    foreach (var n in names)
        if (req.Headers.TryGetValue(n, out var v) && !string.IsNullOrEmpty(v)) return v.ToString();
    return null;
}

app.MapPost(CallbackPath, async (HttpRequest request) =>
{
    // Take HttpRequest (not a bound model) so the body stream is untouched; read the exact bytes.
    using var ms = new MemoryStream();
    await request.Body.CopyToAsync(ms);
    byte[] rawBody = ms.ToArray();

    var ts  = Header(request, "X-Fieldproof-Timestamp", "X-Quikkred-Timestamp");
    var sig = Header(request, "X-Fieldproof-Signature", "X-Quikkred-Signature")?.ToLowerInvariant();
    if (ts is null || sig is null || !long.TryParse(ts, out var tsMs)) return Results.Unauthorized();
    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeMilliseconds() - tsMs) > 5 * 60 * 1000) return Results.Unauthorized(); // ±5 min

    var prefix = Encoding.UTF8.GetBytes($"POST\n{CallbackPath}\n{ts}\n");
    var canonical = new byte[prefix.Length + rawBody.Length];
    Buffer.BlockCopy(prefix, 0, canonical, 0, prefix.Length);
    Buffer.BlockCopy(rawBody, 0, canonical, prefix.Length, rawBody.Length);

    var received = Encoding.UTF8.GetBytes(sig);
    var valid = false;
    foreach (var secret in secrets)
    {
        var expectedHex = Convert.ToHexString(HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), canonical)).ToLowerInvariant();
        if (CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(expectedHex), received)) { valid = true; break; }
    }
    if (!valid) return Results.Unauthorized();

    using var doc = JsonDocument.Parse(rawBody);
    var root = doc.RootElement;
    if (root.GetProperty("type").GetString() == "ping")            // sourceLoanNumber / sequence are null
        return Results.Ok(new { ok = true });

    var eventId = root.GetProperty("eventId").GetString()!;
    if (await Store.InsertEventIfAbsentAsync(eventId, rawBody))    // dedupe on eventId
        Jobs.Enqueue(() => Lms.ApplyFieldproofEventAsync(rawBody)); // apply off the request thread
    return Results.Ok(new { received = true });                     // ack within 10 s
});

app.Run();

// Wire these to your database / job queue (see "Updating your LMS").
static class Store { public static Task<bool> InsertEventIfAbsentAsync(string eventId, byte[] rawEvent) => Task.FromResult(true); } // INSERT ... ON CONFLICT DO NOTHING
static class Jobs  { public static void Enqueue(Func<Task> job) => _ = Task.Run(job); }
static class Lms   { public static Task ApplyFieldproofEventAsync(byte[] rawEvent) => Task.CompletedTask; }               // transactional handler

PHP (plain)​

webhooks/fieldproof.php (PHP 8+)
<?php
declare(strict_types=1);

const CALLBACK_PATH = '/webhooks/fieldproof';   // pathname of the URL you registered (no query string)
$secrets = array_values(array_filter([          // current first; keep the previous one during rotation
    getenv('FIELDPROOF_SECRET_CURRENT') ?: null,
    getenv('FIELDPROOF_SECRET_PREVIOUS') ?: null,
]));

// Wire these to your database / job queue (see "Updating your LMS").
function insertEventIfAbsent(string $eventId, string $rawEvent): bool { return true; } // INSERT ... ON CONFLICT DO NOTHING → true if inserted
function enqueueApply(string $rawEvent): void {}                                       // hand to your worker

if ($_SERVER['REQUEST_METHOD'] !== 'POST') { http_response_code(405); exit; }

$rawBody = file_get_contents('php://input');    // exact bytes — never rebuild from $_POST or json_decode()
$ts  = $_SERVER['HTTP_X_FIELDPROOF_TIMESTAMP'] ?? $_SERVER['HTTP_X_QUIKKRED_TIMESTAMP'] ?? '';
$sig = strtolower($_SERVER['HTTP_X_FIELDPROOF_SIGNATURE'] ?? $_SERVER['HTTP_X_QUIKKRED_SIGNATURE'] ?? '');

if ($ts === '' || $sig === '' || !ctype_digit($ts)
    || abs((int) round(microtime(true) * 1000) - (int) $ts) > 5 * 60 * 1000) {   // ±5 min replay window
    http_response_code(401); exit;
}

$canonical = "POST\n" . CALLBACK_PATH . "\n" . $ts . "\n" . $rawBody;
$valid = false;
foreach ($secrets as $secret) {
    if (hash_equals(hash_hmac('sha256', $canonical, $secret), $sig)) { $valid = true; break; } // lowercase hex, constant time
}
if (!$valid) { http_response_code(401); exit; }

$event = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
header('Content-Type: application/json');
if ($event['type'] === 'ping') { echo json_encode(['ok' => true]); exit; }   // sourceLoanNumber / sequence are null

if (insertEventIfAbsent($event['eventId'], $rawBody)) {   // dedupe on eventId
    enqueueApply($rawBody);                                // apply off the request path
}
echo json_encode(['received' => true]);                    // ack within 10 s

Test your endpoint​

POST /api/v1/partner/webhooks/test

Fires a signed ping at your callback synchronously and returns { success, delivered, statusCode, latencyMs, error, bodyExcerpt } — run it on every deploy of your receiver. 422 CALLBACK_NOT_CONFIGURED means no active callback is registered for this environment. Details on the delivery log page.

Next: Updating your LMS from our events — the transactional handler that turns these deliveries into correct loan records.