Skill: Webhooks and operations

Start with the customer outcome

Deliver results reliably to the customer’s system. Ask only for missing choices that affect the design: the customer’s business flow, launch markets, review team, desired decision and the action their application will enforce. Do not ask for API keys in chat.

Read the current contract

1. Discover current resources at https://docs.toden.co/llms.txt.
2. Read these guides before implementation. They are the same authored source as the human documentation:
   • https://docs.toden.co/integrate/webhooks/overview.md
   • https://docs.toden.co/integrate/webhooks/signatures.md
   • https://docs.toden.co/integrate/webhooks/testing.md
   • https://docs.toden.co/get-started/errors.md
   • https://docs.toden.co/get-started/rate-limits.md
   • https://docs.toden.co/get-started/environments.md
   • https://docs.toden.co/integrate/webhooks/events/billing.md
3. Also read authentication, environments, errors and webhook authentication. Use https://docs.toden.co/get-started/ai/overview.md for API-family boundaries and handoff requirements.
4. For /api/v1 operations, fetch https://api.toden.co/api/openapi.json and resolve referenced schemas. It does not describe /api/kyc or /api/identity: for those fetch https://api.toden.co/api/openapi/verification.json.
5. If the guide and deployed response differ, report the discrepancy and inspect the actual schema. Never invent an endpoint, enum or readiness flag. Use the index SHA-256 values to identify the content reviewed.

Design safeguards

Verify the documented signature against raw request bytes before parsing or acting. Persist a deduplication receipt before acknowledging and process asynchronously. Handle duplicate, late and out-of-order events, rotate keys safely and recover failed deliveries. Webhook events notify; retrieve current authoritative state before a sensitive action. Keep signing secrets server-side and out of traces.

Keep credentials on the customer’s backend. Scope reads and writes to the organisation and environment. Use least-privilege permission checks. Never auto-publish a policy, activate Live, change financial entitlements or approve a company on the user’s behalf without explicit permission. Country coverage and rules are not a guarantee of regulatory compliance; the organisation’s authorised reviewer owns its obligations.

Implement and verify

• Start in Sandbox. Use documented explicit scenarios for deterministic tests; ordinary Sandbox operations can use configured pricing.
• Reuse stable customer and operation references. Send an idempotency key where the operation contract requires one. On an uncertain response, retain the same payload and key and reconcile current state.
• Model pending, review, blocked, unavailable and retryable states explicitly. Never turn an error or missing result into approval.
• Verify signed webhooks on raw bytes, deduplicate and persist before acknowledging, and fetch current state before enforcement.
• Minimise personal data. Do not log keys, raw identity documents, party details, full wallet addresses or biometric evidence.
• Add executable tests for the happy path, invalid input, missing information, tenant/environment isolation, permission denial, duplicate requests, timeout/recovery and out-of-order notifications.
• Use the product’s testing guide for required negative and boundary cases. A mocked success does not prove a real institution channel or Live readiness.

Deliver the customer handoff

Provide the implemented flow, exact API families and versions used, data mapping, decision-to-action table, review owner, webhook recovery procedure, test evidence, and unresolved external prerequisites. Separate local qualification from Sandbox integration and Live acceptance. Suggest workflow improvements with rationale and trade-offs; do not silently change the customer’s risk appetite or claim legal approval.