Build a reliable consumer for PrizePicks API webhooks

A webhook lets your application react to recorded offer changes without repeatedly fetching the entire board. It does not eliminate retries, missing network responses, or the need to check source timestamps. Treat delivery as a transport mechanism around an event that your application must process safely.

Register a public HTTPS receiver

Webhook delivery is part of the Production plan. Register an endpoint in your workspace and select the offer events you need. The endpoint must use public HTTPS on port 443. Localhost and private network destinations are not supported. Save the signing secret when it is shown; later endpoint listings do not reveal it.

Use a separate secret for each integration and keep it in server-side secret storage. A webhook endpoint URL is not a secret by itself. Do not grant access solely because a request reached an obscure path or because it includes a familiar User-Agent.

Verify the exact bytes before parsing

PrizePicks API sends X-Webhook-Timestamp and X-Webhook-Signature headers. The expected signature is v1= followed by the hexadecimal HMAC-SHA256 of timestamp, a period, and the exact raw request body. Use the signing secret as the HMAC key. Reading JSON and serializing it again can change whitespace or object order, so signature validation must use the original bytes.

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

function verify(rawBody, timestamp, signature, secret) {
  if (!/^\d+$/.test(timestamp ?? "")) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  if (!/^v1=[a-f0-9]{64}$/.test(signature ?? "")) return false;
  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`).digest();
  const supplied = Buffer.from(signature.slice(3), "hex");
  return supplied.length === expected.length &&
    timingSafeEqual(supplied, expected);
}

The example rejects timestamps outside a five-minute window and checks lengths before a constant-time comparison. Keep your server clock synchronized. Validate the event schema only after the signature succeeds, then verify that the event type is one your application supports. Node.js documents HMAC creation and timingSafeEqual; the signature format itself comes from this product’s webhook contract.

Make event processing idempotent

A valid event may arrive more than once. Save a durable processed-event record keyed by the event ID and apply the corresponding state update in the same database transaction. If the ID already exists, acknowledge the delivery without applying the change again. The X-Webhook-Id identifies the delivery; the payload event ID identifies the underlying recorded change.

• Receive and verify the raw request. Reject invalid signatures before doing work.
• Persist or enqueue the verified event durably. Do not acknowledge work that only exists in memory.
• Use the event ID to prevent duplicate side effects.
• Return a successful response after durable acceptance. Perform slow downstream work outside the request.

Plan for retries and expired access

The sender retries failed deliveries up to five attempts with increasing delays. Treat that as a bounded retry policy, not a promise that every endpoint outage will eventually recover. Inspect delivery status in your workspace and reconcile missed state with the HTTP projections and change endpoints. A quick 2xx response after durable acceptance reduces needless retries.

Webhook delivery checks Production-plan entitlement and billing holds. If access changes, do not assume a registered endpoint will keep receiving new work. Keep your HTTP reconciliation process aware of its own authentication and request allowance, and show collection timestamps in the resulting product.

Test failure paths before relying on alerts

• Change one byte of a valid body and verify that your receiver rejects it.
• Replay the same event and confirm only one state update occurs.
• Use an old timestamp and reject it even when its HMAC is mathematically valid.
• Return a temporary error and inspect the recorded retry behavior.
• Simulate an unavailable downstream service while your durable queue remains available.