Webhooks API Reference

Webhooks let OilPriceAPI deliver events to your HTTPS endpoint. Use this API-reference page for endpoint mechanics, and the Webhooks Guide for full signing, retry, and cookbook examples.

Lifecycle

1. Create a webhook endpoint.
2. Receive events.
3. Verify HMAC-SHA256 signature.
4. Return a fast 2xx response.
5. Inspect delivery history and retry failures.
6. Test, update, or delete the endpoint.

Endpoints

Signature Verification

Every production webhook receiver should verify signatures before parsing business data.

import crypto from "node:crypto";

function verifyWebhook(payload, timestamp, signature, secret) {
  const message = `${payload}.${timestamp}`;
  const expected = crypto.createHmac("sha256", secret).update(message).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Reject stale timestamps outside your replay window, usually 5 minutes. Store event ids such as evt_... for idempotency.

Event Payload

{
  "id": "evt_123",
  "type": "price.updated",
  "created_at": "2026-07-15T14:30:00Z",
  "data": {
    "code": "WTI_USD",
    "price": 74.52,
    "currency": "USD",
    "created_at": "2026-07-15T14:30:00Z"
  }
}

Error Cases

Related

• Webhook Endpoint Reference
• Webhooks Guide
• Webhook Verification
• Alerts API