Skip to main content

Test Webhook

The Test Webhook endpoint sends a sample event delivery to every URL configured on your signature webhook and returns a per-URL summary of the result. It creates a real delivery record, identical to a delivery triggered by an actual TurboSign event, so it also shows up in List Webhook Deliveries.

When to use it​

Use this endpoint right after creating or updating a webhook to confirm your receiving endpoint is reachable and returns a 2xx response, before relying on it for real signature events.

Example request​

curl -X POST "https://api.turbodocx.com/api/webhooks/signature/test" \
  -H "Authorization: Bearer $TURBODOCX_API_KEY" \
  -H "x-rapiddocx-org-id: $TURBODOCX_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "signature.document.completed",
    "payload": {"documentId": "doc_abc123", "status": "completed"}
  }'

Both eventType and payload are optional; omit them to send a default sample payload for a default event type.

Example response​

{
  "data": {
    "deliveries": [
      {
        "id": "d3a1c2b4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "eventType": "signature.document.completed",
        "url": "https://example.com/webhooks/turbodocx",
        "httpStatus": 200,
        "attemptCount": 1,
        "maxAttempts": 3,
        "isDelivered": true,
        "status": "delivered"
      }
    ],
    "summary": { "total": 1, "successful": 1, "failed": 0, "errors": [] }
  },
  "message": "Test webhook sent successfully to all URLs"
}

If a URL returns a non-2xx status or times out, its entry has isDelivered: false and status: "retrying" (while attempts remain) or "failed" (once all attempts are exhausted), with details in errorMessage. summary.failed/summary.errors do not currently reflect HTTP-level failures; they only count a database error while creating the delivery record, so a URL that returns 4xx/5xx or times out through all attempts still increments summary.successful and leaves summary.errors empty. Inspect each deliveries[] entry's isDelivered, status, and errorMessage to detect a failing receiver rather than relying on summary.failed.

Common errors​

StatusWhenResponse body
401Missing or invalid API key/token, or the organization cannot be resolvedEmpty (status only)
403The key's role is not administratorEmpty (status only)
404No webhook with that name exists in your organization{ "error": "Webhook not found" }
400The webhook exists but isActive is false{ "error": "Cannot test inactive webhook" }
Last updated on