Skip to main content

Create a Webhook Endpoint

Goal​

Implement the receiver endpoint that accepts SpotDraft webhook deliveries safely.

Overview​

This page is a focused companion to Receive Real-Time Contract Events via Webhooks. Use the main playbook for the full registration and delivery flow. Use this page when you only need the receiver implementation notes.

Endpoints used​

  • POST <your webhook endpoint>
  • GET /api/v2.1/public/webhooks/hmac_key/

Prerequisites​

  • a public HTTPS endpoint that accepts POST requests
  • access to the raw request body
  • the webhook hmac_key from SpotDraft

1. Expose a public HTTPS endpoint​

Your service should expose an HTTPS endpoint that accepts POST requests from SpotDraft. Use a publicly trusted certificate and keep the endpoint lightweight.

2. Register the webhook​

In SpotDraft, go to Settings -> Developer settings -> Webhooks and register the endpoint with the event types your integration needs, or follow the exact API-based setup in Receive Real-Time Contract Events via Webhooks.

3. Verify the request body​

For new integrations, verify X-SD-WEBHOOK-CONTENT-HASH using your hmac_key before doing any business processing.

import base64
import hashlib
import hmac

def verify_spotdraft_webhook(request, hmac_key: str) -> None:
    signature = hmac.new(
        base64.b64decode(hmac_key),
        request.body,
        digestmod=hashlib.sha512,
    ).hexdigest()

    if not hmac.compare_digest(
        signature,
        request.headers["X-SD-WEBHOOK-CONTENT-HASH"],
    ):
        raise ValueError("invalid webhook signature")

4. Make processing idempotent​

Persist the raw payload, deduplicate repeated deliveries, and move slow processing into a background queue.

Practical rules:

  • store the payload before downstream handling
  • make retries safe by checking a delivery identifier or payload fingerprint
  • return 2xx only after verification and persistence
  • let queue workers do the expensive work

5. Validate the delivery flow​

Use product-side webhook logs in the SpotDraft UI together with your own ingress, application, queue, and worker logs to inspect recent requests, failures, and specific contract identifiers. API logs are not exposed. If you see repeated failures, verify certificate validity, signature handling, and response times.

Production notes​

  • Keep the receiver fast and push slow work into a queue.
  • Verify the signature before any business processing.

Common failure points​

  • verifying a parsed payload instead of raw bytes Signature checks must run against the exact raw body that arrived over HTTP.