Skip to main content

Webhooks

Webhooks notify your server when contract lifecycle events happen in SpotDraft. Register one or more HTTPS endpoints in Settings -> Developer settings -> Webhooks, choose the event types, and SpotDraft delivers an HTTP POST with a JSON payload.

Return a 2xx response quickly. Queue slow work so timeouts do not count as failed deliveries.

Delivery requirements​

  • Use HTTPS with a publicly trusted certificate.
  • Keep the endpoint publicly reachable from SpotDraft.
  • Support multiple webhook URLs per account when different systems need separate receivers.
  • Subscribe only to the event types your integration needs.
  • Acknowledge quickly and process downstream work asynchronously.

Verification​

Use X-SD-WEBHOOK-CONTENT-HASH for verification. Validate the raw request body with HMAC-SHA512 using the hmac_key returned by the HMAC key API.

import base64
import hashlib
import hmac

signature = hmac.new(
    base64.b64decode(sample_hmac_key),
    request.body,
    digestmod=hashlib.sha512,
).hexdigest()

assert signature == request.headers["X-SD-WEBHOOK-CONTENT-HASH"]

Compare against the raw request body bytes before any JSON parsing or normalization.

Processing model​

Use this production shape:

  1. read the raw request body
  2. verify X-SD-WEBHOOK-CONTENT-HASH
  3. parse the JSON payload
  4. persist a delivery id, event id, payload hash, or other dedupe key
  5. enqueue downstream work
  6. return 2xx quickly
  7. let a worker update CRM, ERP, storage, warehouse, notification, or internal systems

Webhook delivery is a change signal. If downstream systems need the latest complete record, fetch the contract, document, metadata, or status from the API after receiving the event.

Common activity types​

activity valueWhen it fires
CONTRACT_CREATEDA new contract is created
CONTRACT_DATA_UPDATEDContract data changes
CONTRACT_SENT_TO_COUNTERPARTYThe contract is sent for counterparty review or redlining
CONTRACT_SIGNATURE_REQUESTEDThe contract is marked or sent for signature
CONTRACT_SIGNEDA required signatory completes signing
CONTRACT_EXECUTEDAll required signatures are complete
CONTRACT_PROCESS_METRIC_UPDATEDWorkflow metrics change

Use the API reference for version-specific webhook endpoints and sample payload operations.

Debugging expectations​

SpotDraft does not expose product-side webhook logs in the developer portal. Your receiver must own delivery observability.

At minimum, log:

  • endpoint URL and environment
  • event type or activity
  • contract id or reference id when present
  • delivery id, event id, or payload hash
  • signature verification result
  • queue job id
  • response status returned to SpotDraft
  • downstream processing result

When investigating failures, confirm that the destination URL belongs to the same region and environment strategy you use for the rest of the integration and that your endpoint returns a 2xx quickly.