Webhooks

RakeSign webhooks subscribe to events from one team. They exclude participant-only documents. An integration can manage only its own endpoints within its team. Administrators can manage endpoints for teams they manage.

Register an endpoint

Choose a public HTTPS endpoint and an explicit event list. The key needs webhooks:write and the read scope for the selected event family.

curl --fail-with-body -sS \
  https://api.cloudraker.com/v1/signing/webhooks \
  -H "Authorization: Bearer $RAKESIGN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/hooks/rakesign",
    "teamId": "YOUR_TEAM_ID",
    "events": ["document.completed", "document.failed", "delegation.granted"]
  }'

Document and recipient events require documents:read. Delegation events require delegations:read. Delivery requires webhooks:write and the event family’s read scope to remain active. Use webhooks:read to list endpoints and inspect delivery history.

Events

The payload contains identifiers, not document contents, signer email addresses, or signing links:

{
  "eventId": "8357b4b4-9b6f-4126-9b67-23c804b610d4",
  "type": "document.completed",
  "occurredAt": "2026-10-24T15:00:00.000Z",
  "data": {
    "documentId": "YOUR_DOCUMENT_ID",
    "runId": "YOUR_RUN_ID",
    "envelopeId": "YOUR_ENVELOPE_ID"
  }
}

Depending on the event, data can include signerId, delegationId, templateId, and templateRevision. Use the relevant read endpoint to fetch the current resource. Delivery order is not guaranteed.

Verify every delivery

The x-rk1-signature header contains an ES256 JWT. Verify it with the public keys at https://api.cloudraker.com/v1/webhooks/jwks.json. This endpoint is public and does not require a key.

Check the issuer rakerone-process, algorithm ES256, and token expiry. Compute the SHA-256 hash of the exact request body bytes. Its base64url value must match the JWT’s bodySha256 claim. Also match the JWT’s eventId and type to the payload.

The JWT’s processingId identifies the document, delegation, or event. RakeSign payloads carry resource IDs under data; they do not include a top-level processingId.

See the signature verifier for the shared verification code. Preserve the raw request body until verification finishes.

Retry behavior

Deliveries can occur more than once. Deduplicate by eventId before your handler performs work. Return a 2xx response after you store the event durably.

RakeSign makes up to six attempts. Failed attempts wait approximately 10 seconds, 30 seconds, 2 minutes, 10 minutes, and 1 hour before the next attempt. Network failures and non-2xx responses count as failed attempts. A destination blocked by URL validation stops delivery without further attempts.

Each request has a ten-second timeout per redirect hop. Delivery follows at most five redirects and checks each destination. Register the final HTTPS URL to avoid unnecessary redirects.

Before every attempt, RakeSign checks the endpoint, permissions, and current resource access. Revoked access, a disabled endpoint, or a removed subscription stops further delivery.

Inspect and replay

These paths use the /v1/signing prefix. Replay requires webhooks:write and read access for the event family. The response is 202 with { "accepted": true, "eventId": "..." }. It confirms scheduling, not receiver success.

Send an Idempotency-Key header when a replay request might need a retry. Use 8 to 200 printable characters without spaces. Repeating the same key for the same endpoint and event reuses that replay, even after it completes. Completed replay keys remain effective for at least 90 days after completion. Cleanup removes expired keys asynchronously. Reusing a key after removal can deliver the event again. Use a new key for a separate replay. Without a key, RakeSign reuses an existing pending delivery when available.

Replay preserves the event ID and checks current access again. Resume a paused endpoint before replaying a recorded event. Events created while the endpoint is paused do not target that endpoint.

The RakeSign Developers → Webhooks page exposes the same delivery history and replay operation. Attempt records include status codes and timestamps, without response bodies or credentials.

History retention

Completed delivery attempts and terminal jobs expire after 90 days. Pending jobs and their event records remain available until delivery stops or completes. Cleanup preserves old attempts while their job remains pending.

Event retention starts when RakeSign receives the event, not at the source event timestamp. A replay or delivery attempt renews event retention for 90 days. Events with expired retention cannot start a new replay. Cleanup runs daily in bounded batches and continues without new API traffic.

Your receiver must deduplicate the stable event ID, including after replay-key history expires. This retention policy does not remove signing documents, signatures, or consent evidence.