1. Webhooks
Handwrite
  • Handwrite Regular Accounts
    • Start here — Handwrite for outside developers
    • API specification notes
    • Socket specification notes
    • Account
      • README — GET /api/v1/me
      • README — DELETE /api/v1/me
      • README — GET /api/v1/me/policy
      • README — GET /api/v1/me/usage
      • Account API — README
      • Who this credential acts for
      • Delete the account (after a 30-day grace period)
      • What your teams' and classes' policies allow
      • Your own usage, and what your teams and classes counted
    • Documents
      • README — GET /api/v1/documents
      • README — POST /api/v1/documents
      • README — GET /api/v1/documents/search
      • README — GET /api/v1/documents/{id}
      • README — PATCH /api/v1/documents/{id}
      • README — DELETE /api/v1/documents/{id}
      • README — GET /api/v1/documents/{id}/content
      • README — PUT /api/v1/documents/{id}/content
      • README — POST /api/v1/documents/{id}/live
      • README — GET /api/v1/export
      • Documents API — README
      • List your documents (or shared, or changes since)
      • Create a document
      • Search your own and shared documents
      • A document's metadata
      • Change title, text, content type or language
      • Delete a document (owner)
      • The document's text
      • Replace the text
      • Join the document's live co-editing room
      • Every document you own, with its text
    • Files
      • README — GET /api/v1/documents/{id}/file
      • README — POST /api/v1/documents/{id}/file
      • README — POST /api/v1/documents/{id}/file/commit
      • README — POST /api/v1/documents/{id}/extract
      • Files API — README
      • Download the original file
      • Start uploading the original file
      • Make an uploaded file the document's file
      • Replace the text with the file's text
    • Audio
      • README — GET /api/v1/documents/{id}/audio
      • README — POST /api/v1/audio/stream
      • README — POST /api/v1/audio/speech
      • README — GET /api/v1/voices
      • README — GET /api/v1/quota
      • Audio API — README
      • The whole document as one audio file
      • Stream speech as it's made
      • Speech with word timings (read-along)
      • Voices you can use
      • Characters left, limit, plan and reset time
    • Sharing
      • README — GET /api/v1/documents/{id}/permissions
      • README — POST /api/v1/documents/{id}/permissions
      • README — PATCH /api/v1/documents/{id}/permissions/{principal}
      • README — DELETE /api/v1/documents/{id}/permissions/{principal}
      • README — DELETE /api/v1/documents/{id}/invitations/{inviteId}
      • README — GET /api/v1/invitations
      • README — POST /api/v1/invitations/{id}/accept
      • README — POST /api/v1/invitations/{id}/decline
      • Sharing API — README
      • Who a document is shared with
      • Share by principal, or invite by email (owner)
      • Change someone's role (owner)
      • Remove access (owner, or leave yourself)
      • Cancel a pending invitation (owner)
      • Document invitations to your verified email
      • Accept a document invitation
      • Decline a document invitation
    • Settings
      • README — GET /api/v1/settings
      • README — PATCH /api/v1/settings
      • Settings API — README
      • Synced app and reader settings
      • Change settings (per key, the newer updatedAt wins)
    • Webhooks
      • Incoming webhook delivery — README
      • README — GET /api/v1/webhooks
      • README — POST /api/v1/webhooks
      • README — GET /api/v1/webhooks/{id}
      • README — DELETE /api/v1/webhooks/{id}
      • Webhooks API — README
      • Your webhook endpoints
        GET
      • Register an endpoint (up to 10)
        POST
      • One endpoint
        GET
      • Delete an endpoint (queued retries are dropped)
        DELETE
    • Meta
      • README — GET /api/v1/openapi.json
      • Meta API — README
      • This OpenAPI description
    • OAuth
      • README — POST /api/oauth/token
      • README — POST /api/oauth/revoke
      • OAuth API — README
      • Exchange a code, or refresh
      • Revoke a token (RFC 7009)
    • Live socket
      • Live document socket — README
    • A document or sharing event
    • Schemas
      • Error
      • Principal
      • Role
      • Access
      • ContentType
      • Language
      • FileRef
      • Document
      • Tombstone
      • DocumentPage
      • CreateDocument
      • UpdateDocument
      • FileInfo
      • CommitUpload
      • Upload
      • DownloadLink
      • Extracted
      • ExtractionFailed
      • CommittedDocument
      • ExtractedDocument
      • SearchHit
      • SearchPage
      • Export
      • Permission
      • Share
      • ChangeRole
      • Invitation
      • Permissions
      • ReceivedInvitation
      • AcceptedInvitation
      • Me
      • WebhookEventType
      • Webhook
      • CreateWebhook
      • CreatedWebhook
      • WebhookDelivery
      • AudioFormat
      • Speech
      • WordTiming
      • SpeechMarks
      • AudioLink
      • Voice
      • Quota
      • SettingEntry
      • Settings
      • SettingsPatch
      • PatchedSettings
      • OAuthToken
      • OAuthError
  • Handwrite Team
    • Schemas
      • Error
      • Principal
      • Access
      • ContentType
      • Language
      • FileRef
      • Document
      • Tombstone
      • DocumentPage
      • OrgKind
      • OrgRole
      • Organisation
      • CreateOrganisation
      • RenameOrganisation
      • Member
      • AddMember
      • ChangeMember
      • InviteMember
      • OrgInvitation
      • ReceivedOrgInvitation
  • Handwrite Classroom
    • Schemas
      • Error
      • Principal
      • Access
      • ContentType
      • Language
      • FileRef
      • Document
      • Tombstone
      • DocumentPage
      • OrgKind
      • OrgRole
      • Organisation
      • CreateOrganisation
      • RenameOrganisation
      • Member
      • AddMember
      • ChangeMember
      • InviteMember
      • OrgInvitation
      • ReceivedOrgInvitation
  1. Webhooks

Incoming webhook delivery — README

Handwrite sends POST requests to the HTTPS receiver URL you register using the Webhooks API. This is a callback contract, not another path on handwrites.io. The API reference named A document or sharing event describes this incoming request body.

Validate before processing#

Capture the exact raw request body. Read Handwrite-Event-Id, Handwrite-Event-Type and Handwrite-Signature. The signature has t=<unix seconds>,v1=<hex> and authenticates <t>.<raw body> using HMAC-SHA256 with the signing secret returned once when the endpoint was registered. Reject malformed signatures and timestamps outside a five-minute window. Use constant-time comparison and then parse the authenticated JSON.
Deduplicate by event ID using persistent storage. Return any 2xx within 10 seconds after durable acceptance, then process asynchronously. A timeout, non-2xx response or redirect is a failed attempt. There are up to eight attempts total; delays grow approximately 1, 2, 4, 8, 16, 32 and 64 minutes. A duplicate is normal and should not repeat side effects.

Payload and recovery#

The body contains id, type, created, and data with a document reference and actor. Sharing events also include a permission change. Fetch the current document through the REST API when needed; handle deletion or removed access. Use incremental document sync to recover from a receiver outage. Do not assume notifications arrive once or in order.
Event types: document.created, document.updated, document.deleted, document.shared, permission.removed.
This receiver uses a webhook signing secret, not an API bearer token. Never place that secret in responses, logs, client bundles or the receiver URL. See API specification notes for the complete delivery and account-access rules.

Webhook compatibility snapshot — 2026-10-26#

The published OpenAPI still lists personal webhook registration. Current working-tree code instead rejects new personal receivers with 403 webhooks_moved; new receivers belong to teams/classes and are managed by an administrator in the organisation Developer tab. Existing personal receivers continue to receive events in that code. Deployment of this change and live runtime behavior were not verified here. Treat the registration reference as the published contract, not proof that new personal registration is available. The Team and Classroom editions describe the organisation workflow.
Modified at 2026-10-26 13:12:37
Previous
Change settings (per key, the newer updatedAt wins)
Next
README — GET /api/v1/webhooks
Built with