> This page is for RakeSign.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cloudraker.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cloudraker.com/_mcp/server.

# 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.

```bash
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

| Family     | Event types                                                                                                             |
| ---------- | ----------------------------------------------------------------------------------------------------------------------- |
| Documents  | `document.sent`, `document.completed`, `document.declined`, `document.expired`, `document.cancelled`, `document.failed` |
| Recipients | `recipient.viewed`, `recipient.signed`, `recipient.approved`, `recipient.declined`                                      |
| Delegation | `delegation.requested`, `delegation.granted`, `delegation.declined`, `delegation.revoked`, `delegation.contested`       |

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

```json
{
  "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](/paperwork/developers/webhooks#sample-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

| Route                                           | Result                                       |
| ----------------------------------------------- | -------------------------------------------- |
| `GET /webhooks`                                 | List accessible endpoints.                   |
| `PATCH /webhooks/:id`                           | Change `url`, `events`, or `disabled`.       |
| `DELETE /webhooks/:id`                          | Delete the endpoint.                         |
| `GET /webhooks/:id/deliveries`                  | Read the 100 most recent delivery attempts.  |
| `POST /webhooks/:id/deliveries/:eventId/replay` | Queue a recorded event for another delivery. |

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.