Update errors, pagination and webhooks documentation

[ricardobcl]

Description

Fixes drift between the Errors, Pagination and Webhooks pages and the current behavior of the platform, verified against uphold/backend master and uphold/event-dispatcher master.

_errors.md

• Added 410 Gone, 422 Unprocessable Entity and 423 Locked to the status table — all verified as actually emitted by the API. 415 was deliberately left out: the error class exists but has no callers.
• Documented the two error response body shapes, which were previously undocumented: HTTP errors ({ "code": "<snake_cased_status>", "message": "<status name>" }) and validation errors ({ "code": "validation_failed", "errors": { ... } }).

_pagination.md

• Documented that successful paginated responses return 206 Partial Content with an Accept-Ranges: items header — integrators checking for 200 would be surprised.
• The 50-items-per-page maximum applies to most endpoints, not all (e.g. the assets list allows 150).
• Grammar fix in the intro.

_webhooks.md

• Named the signature header (Signature) and specified the actual scheme: HMAC-SHA512 of the JSON-serialized body with the shared secret, hex-encoded, prefixed with sha512= — previously described only as "signing with the SHA512 algorithm", which is not enough to verify a delivery. Added a verification hint.
• Transaction status webhook: any status transition is forwarded (there is no whitelist), and the status list now matches the backend enum (cancelled, completed, failed, on-hold, processing, waiting).
• Card updated webhook: the payload carries only the card id plus context, not full card details; added a pointer to the Get Card Details endpoint.
• Delivery scoping: notifications are determined by the webhook subscription's configuration (event type and optional entity/user filters), not by "transactions created by your application", which the dispatcher does not enforce.

Notes for reviewers

• Webhook behavior was verified against uphold/event-dispatcher master (crypto-util.js, webhook-dispatcher/app.js, the event handlers and subscription-manager.js).
• Whether the webhook shared secret differs from the OAuth client secret could not be determined from code (subscriptions are seeded manually); the docs' existing wording on the secret was left untouched.

Related issues

Follow-up to #250 (documentation audit against uphold/backend master).

Impacted areas

Errors, Pagination and Webhooks pages of the API reference.

Steps to reproduce or test

Development

Every claim was traced to the enforcing code in uphold/backend master (error mappers, koa-pagination middleware and controller overrides) and uphold/event-dispatcher master (signing and dispatch paths).

QA

Render the three pages; optionally verify a paginated endpoint returns 206 + Accept-Ranges: items and that a webhook delivery's Signature header validates with the documented HMAC-SHA512 scheme.

Checklist

• Add label Breaking Change if it applies.
• Commits are atomic and logically separated.
• Performance implications have been considered.
• Security implications have been considered.
• API documentation, if required, has been created or updated.
• New dependencies have been added to package.json.
• The README file, if required, has been updated.
• Architectural diagram, if required, has been updated.

Deploy notes

N/A — no files added or removed, so no slate index changes are needed.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This documentation-only PR aligns the Errors, Pagination, and Webhooks API reference with current platform behavior.

Changes:

• Adds error statuses and response formats.
• Clarifies pagination responses and limits.
• Documents webhook signing, payloads, filtering, and statuses.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Summary
_webhooks.md	Clarifies signatures, payloads, delivery scoping, and event statuses.
_pagination.md	Documents pagination headers, status codes, and limits.
_errors.md	Adds error statuses and response-body formats.

Suppressed comments (3)

_webhooks.md:103

• This sentence still says that creating a transaction returns processing unconditionally, but the create/commit documentation states that the create/prepare endpoint returns pending and only commit (or ?commit=true) changes it to processing (_transactions.md:150,192). Please distinguish the prepare and commit paths here so consumers do not miss the initial pending status.

When you create a transaction, the first set of validations is run and you'll get an error if the transaction request is not valid. Otherwise, the request is completed successfully and the response body will contain a `status` property with value `processing`. In the meantime, we perform another set of validations that can lead to a transaction's `status` becoming `failed` or `completed`. This asynchronous behavior can be handled by subscribing to a webhook with the "Transaction Status Updated" scope, which will allow you to receive updates whenever a transaction changes its `status`.

_webhooks.md:23

• The comma before “that” makes this newly edited sentence grammatically incorrect. Remove it so the relative clause is attached to the Signature header correctly.

In addition, the request also includes a `Signature` header, that can be used to verify that the request body has not been tampered with.

_webhooks.md:128

• This new table entry says every status transition is forwarded, but the preceding paragraph still describes the asynchronous status change as only becoming failed or completed. That contradiction leaves readers unsure whether transitions such as cancelled, on-hold, or waiting are actually delivered; update the preceding description to say that forwarded updates cover any transition.

|         | Any status change is forwarded. Statuses include: `cancelled`, `completed`, `failed`, `on-hold`, `processing` and `waiting`.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.