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 your own ingress, application, queue, and worker logs to inspect recent requests, failures, and specific contract identifiers. SpotDraft does not expose product-side webhook logs in the developer portal. 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.