​

Webhook Security

​

Signature Verification

• The signature is the HMAC-SHA256 of the raw request body, exactly as received, encoded as lowercase hexadecimal (64 characters). There is no prefix such as sha256=.
• The key is the webhook_secret returned when you registered the subscription, used as a UTF-8 string exactly as returned. Do not decode it.
• Each subscription (target URL, event type and pharmacy scope) has its own webhook_secret. If you receive several event types at the same endpoint, use the X-Webhook-Event header to pick the secret of the matching subscription.
• There is no separate timestamp header. The timestamp field in the body is covered by the signature.

​

Example (Python)

import hashlib
import hmac


def verify_webhook(raw_body: bytes, signature: str, webhook_secret: str) -> bool:
    # raw_body: the request body exactly as received, e.g. request.get_data() in Flask
    if not signature:
        return False
    expected = hmac.new(
        webhook_secret.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

​

Example (Node.js)

const crypto = require('crypto');

// rawBody: the request body as a Buffer, exactly as received,
// e.g. with express.raw({ type: 'application/json', limit: '10mb' })
function verifyWebhook(rawBody, signature, webhookSecret) {
  if (typeof signature !== 'string') {
    return false;
  }
  const expected = Buffer.from(
    crypto.createHmac('sha256', webhookSecret).update(rawBody).digest('hex'),
  );
  const received = Buffer.from(signature);
  return expected.length === received.length
    && crypto.timingSafeEqual(expected, received);
}

​

Webhook Secret

• The webhook_secret is returned only once: in the response to POST /v1/external_pharmacy_api/webhooks/, or in the Pharmacy Portal right after you register a webhook. It is stored encrypted and cannot be retrieved later — GET /v1/external_pharmacy_api/webhooks/ never returns it.
• Each subscription has its own secret. X-Webhook-Event tells you the event type of a delivery, but nothing identifies the subscription itself, so subscriptions that share an event type — for example one per pharmacy of a group — cannot be told apart. Give those a separate target URL each (for example a different path or query parameter), so you always know which secret to verify with.
• The value of a custom header (header_value) is never returned either; only its name (header_key) is.

​

Rotating the Secret

​

Best Practices