Skip to main content

Troubleshooting

When an integration is failing, reduce the problem to one API request or one webhook delivery. SpotDraft does not expose product-side API or webhook logs in the developer portal, so your integration must keep the operational logs needed for debugging.

Debug an API call​

  1. Confirm the regional base URL and path. The full request should use the workspace region and a versioned public path such as /api/v2.1/public/....
  2. Disable automatic redirects while debugging. A 302 commonly means http:// was used instead of https://, or the trailing slash does not match the documented route.
  3. Confirm the credentials were generated in the same workspace and environment as the request target.
  4. Check whether user-email is being passed intentionally. If it is present, the user must be active in the workspace and allowed to perform the action.
  5. Validate all workspace-specific ids: contract type id, template id, entity id, counterparty id, contract id, role id, and metadata keys.
  6. Inspect the response status and body. Treat 400, 401, 403, 404, and 409 as request, permission, or state problems before retrying.
  7. Retry only transient failures such as 429, timeouts, and selected 5xx responses with bounded exponential backoff and jitter.

Log the method, regional host, path, environment, status code, internal request id, retry count, and any external metadata key involved. Do not log client-secret, bearer tokens, or signed document URLs.

Debug a webhook​

  1. Confirm the webhook is registered in the same SpotDraft environment where the contract activity occurred.
  2. Confirm the endpoint is public, uses HTTPS, has a valid certificate, and accepts POST requests.
  3. Confirm the subscription includes the event type you expect.
  4. Check your ingress logs for the exact request time. There are no SpotDraft-side webhook logs exposed in the product for you to inspect.
  5. Verify the signature using X-SD-WEBHOOK-CONTENT-HASH and the raw request body before JSON parsing.
  6. Confirm the receiver returns 2xx quickly and moves slow work into a queue.
  7. Check dedupe and idempotency handling. Duplicate deliveries should not create duplicate downstream updates.
  8. Check worker logs for the downstream job that processed the event.
  9. If downstream state is stale, fetch fresh contract or document state from the API and run a reconciliation job.

Log the event type, contract id, delivery id or payload hash, signature result, queue job id, response code, retry count, and downstream processing result.

Debug environment drift​

If the same code works in UAT but fails in production, compare:

  • API base URL
  • API credentials
  • contract type ids
  • template ids
  • questionnaire and intake-form fields
  • creator entities
  • user and role membership
  • webhook endpoint URL and event subscriptions
  • downstream secret configuration

Do not copy UAT identifiers into production code or production identifiers into UAT fixtures.

When to escalate​

Escalate only after you can provide a minimal failing example:

  1. exact endpoint or webhook event
  2. environment and region
  3. timestamp
  4. request method and status code
  5. sanitized request body or webhook payload
  6. contract id or external metadata id
  7. your internal request id, delivery id, or queue job id