{"id":19320,"plugin_id":"plugins_6a9669d9e57c8191a04a3c8951e44401","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:15:29.743Z","digest":"ceaa7f70f504edb6a8d7fcd63ee4fdf147373b11b860e2d6f7372795563731c2","against":null,"payload":{"description":"Design, implement locally, or evaluate YCloud webhook endpoint management and secure receivers from the official signature, retry, acknowledgement, and delivery contract. Use for endpoint CRUD/rotate-secret integration or event receiving; do not use for message sending, readiness, broad integration planning, or real endpoint/API mutations.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":287},{"relative_path":"references/openapi.md","size_in_bytes":20976},{"relative_path":"references/runtime.md","size_in_bytes":17104},{"relative_path":"references/shared/integration-boundaries.md","size_in_bytes":8401},{"relative_path":"references/shared/pagination-contract.md","size_in_bytes":3494},{"relative_path":"references/shared/sandbox-contract.md","size_in_bytes":5363},{"relative_path":"references/shared/webhook-contract.md","size_in_bytes":7212},{"relative_path":"references/shared/webhook-event-types.txt","size_in_bytes":1071},{"relative_path":"references/shared/webhook-message-lifecycle-fixtures.json","size_in_bytes":3555},{"relative_path":"references/shared/webhook-signature-vectors.tsv","size_in_bytes":4350}],"name":"ycloud-webhook-endpoints","skill_md_contents":"---\nname: ycloud-webhook-endpoints\ndescription: Design, implement locally, or evaluate YCloud webhook endpoint management and secure receivers from the official signature, retry, acknowledgement, and delivery contract. Use for endpoint CRUD/rotate-secret integration or event receiving; do not use for message sending, readiness, broad integration planning, or real endpoint/API mutations.\n---\n\n# YCloud Webhook Endpoints\n\nFor endpoint-list work, read\n[`references/shared/pagination-contract.md`](references/shared/pagination-contract.md)\nwith the generated OpenAPI/runtime references.\n\nDesign or implement endpoint-management integrations from the pinned OpenAPI\ncontract and receiver integrations from the reviewed official runtime contract.\nKeep those two modes distinct in the result.\n\n## Execution boundary\n\nThese restrictions govern Skill execution: do not call a YCloud Provider API, access real credentials, or read real business data. The Skill may generate server-side adapter code for an application's runtime, but must not start it or make a live request. Reading public official documentation as contract evidence is allowed and is not a Provider API call or business-data access. A live smoke test is outside the default workflow and requires separate, explicit authorization naming the target/environment, allowed operations, credential boundary, and required result evidence.\n\nHonor Architect handoffs for `scope`, `deliverable`, `mutation`, capability IDs,\nproject seams, and expected evidence. Without one, default to focused scope and\nread-only guidance unless the user explicitly requests local implementation.\nLocal-write authorization permits endpoint request builders, adapters, receiver\nhandlers, inbox/state models, test-console bindings, synthetic fixtures, and\nno-network tests inside the scoped project. It never authorizes endpoint create,\nupdate, delete, secret rotation, callback delivery, or any real API call. Reuse\nthe project's existing UI/interface stack; do not create a dashboard or choose a\nframework on your own.\n\n## Trigger boundary\n\nUse this skill for creating, listing, retrieving, updating, deleting, or rotating\nthe secret of a YCloud webhook endpoint, and for receiver acknowledgement,\nsignature verification, retry/deduplication handling, or event-delivery design.\nEndpoint CRUD comes from `references/openapi.md`; receiver behavior comes from\n`references/runtime.md`. Event-type-specific payload fields beyond the documented\ncommon envelope require a selected event reference or remain `CANNOT`. Route message operations to `ycloud-whatsapp-messages`, media upload\nto `ycloud-whatsapp-media`, template lifecycle to `ycloud-whatsapp-templates`,\nand broad integration design to `ycloud-integration-architect`. Readiness and\nRepository-maintenance and issue-tracker prompts do not trigger this skill.\n\nAfter selection, read `references/openapi.md` and `references/runtime.md`. In\nreceiver mode, also read `references/shared/webhook-contract.md`,\n`references/shared/webhook-event-types.txt`, and\n`references/shared/webhook-signature-vectors.tsv`. For\n`whatsapp.message.updated`, also execute\n`references/shared/webhook-message-lifecycle-fixtures.json`. For receiver reliability,\nerror translation, replay, secret rotation, or callback-URL security, also read\n`references/shared/integration-boundaries.md`. The OpenAPI reference mechanically lists the\nsix allowlisted endpoint-management operations: create, list, retrieve, update,\ndelete, and rotate-secret. Use the exact source-derived paths, methods,\noperationIds, parameters, request/response schemas, and descriptions. Never\ninvent endpoint paths, event payload fields, retry behavior beyond the published\nschedule, delivery semantics, or rotation choreography. The runtime reference\ndoes confirm `YCloud-Signature`, HMAC-SHA256 over `<timestamp>.<raw-body>`, a\nfast `2xx`, and seven retry intervals; do not put those facts in `CANNOT`. If\nthe reference is missing or its source hash/coverage drifts, report the drift\nand stop.\nInterpret `allOf` as schema composition and `x-*` extensions or generated model\nnames as codegen hints, not endpoint runtime behavior.\n\nFor explicitly requested sandbox/mock/no-real-side-effect receiver testing,\nalso read `references/shared/sandbox-contract.md`. Its local event producer and\n`/_mock/*` transitions are synthetic test controls, not endpoint-management\noperations or YCloud delivery guarantees.\n\n## Workflow\n\n1. Identify the intended endpoint operation and inspect only explicitly scoped,\n   non-secret project files for runtime and deployment facts. Ask for missing\n   facts; do not assume a framework, SDK, endpoint URL, environment, or secret\n   store.\n2. Match one of the six operations in the generated reference. Preserve exact\n   path parameters, request/response schemas, and description-only constraints.\n   Treat `operationId` as a contract identifier, never as an SDK method name.\n3. Generate a raw HTTP or contract-aware typed example, or implement local\n   request/receiver seams when authorized, with placeholders such as\n   `<YCLOUD_API_KEY>`, `<ENDPOINT_ID>`, `<CALLBACK_URL>`, and synthetic values.\n   Give SDK-specific code only when the user provides a confirmed artifact,\n   version, and documentation. Do not make a live request or change a project.\n4. Keep API keys and endpoint secrets server-side and out of browsers, mobile\n   clients, URLs, logs, source control, and generated snippets. Never read,\n   print, validate, or rotate a real credential.\n5. In receiver mode, preserve the raw body bytes, require the exact lowercase\n   `t=<unix-seconds>,s=<64-hex>` shape, and compute HMAC-SHA256 over ASCII\n   timestamp, one period byte, and the unchanged body bytes. Add no trailing delimiter.\n   Compare digest bytes in constant time against every\n   explicitly configured candidate secret, and apply the configurable\n   Developer Kit 300-second bidirectional tolerance before JSON processing.\n   Resolve tenant identity from a trusted endpoint mapping, not an untrusted\n   payload.\n   Treat `X-Webhook-Endpoint-ID` as correlation metadata that must match the\n   trusted route/configuration mapping. Never let that caller-controlled header\n   select a tenant, secret, or inbox partition by itself.\n   Do not parse or classify the event before successful verification. An invalid\n   signature is rejected transport evidence, not a duplicate/conflict event.\n   Persist a scoped inbox identity such as\n   `(provider, webhook_endpoint_id, event_id)` and payload hash. Return `2xx`\n   quickly (within 6 seconds is recommended) only after durable acceptance,\n   then enqueue work. Label the 300-second tolerance, transport replay claim,\n   and 24-hour event-inbox retention as recommended policy, not YCloud\n   guarantees.\n   Preserve `X-Webhook-Endpoint-ID` for routing/correlation without logging\n   secrets.\n6. In endpoint-design mode, require a publicly reachable URL, reject private or\n   internal IPs, prefer HTTPS, and account for the documented limit of 20\n   endpoints per account. List operations use 1-based page-number pagination\n   with `page` and `limit` 1..100 and optional `includeTotal`. Parse the response\n   as the merged Page envelope: required `offset`, `limit`, `length`, endpoint\n   `items`, and optional `total`; do not send `offset` as a query parameter or\n   unwrap a nonexistent `data` field.\n7. Apply the recommended durable-acceptance response boundary: invalid\n   signature returns `401` without enqueue; invalid common envelope before\n   persistence returns `400`; a same-hash duplicate or durably recorded unknown\n   event returns `2xx`; an inbox persistence failure returns `503`; business\n   failure after the earlier `2xx` uses internal retry/DLQ. For a scoped event-ID\n   collision with a different hash, quarantine and alert, and acknowledge only\n   after the conflict is durably recorded. Label this matrix as platform policy,\n   not a YCloud response schema.\n   Never deduplicate by event type, `whatsappMessage.id`, status, `wamid`, or\n   payload hash alone. Keep `inboxClassification` separate from message\n   `projectionOutcome`: different event IDs for one message are new events even\n   when a projection is unchanged or out of order. Ignore the Sandbox\n   classification header and compute classification from verified bytes.\n8. Explain response handling only from the references. Separate endpoint\n   registration state from payload receipt and message delivery. If the user\n   wants to send a message after endpoint setup, hand off to\n   `ycloud-whatsapp-messages`.\n9. Use the shared TSV vectors when generating or testing Java, Node, Go, or PHP\n   verification code. The wrong-secret, stale/future timestamp, tampered body,\n   JSON-reserialized body, trailing-delimiter, and malformed-header rows must\n   fail. Do not create replacement vector values inside the response.\n10. Provide synthetic tests for request validation, public-URL checks, endpoint\n   count/pagination boundaries, endpoint identity mapping,\n   raw-body signature verification, invalid/missing/stale signatures, same-event\n   duplicate/conflict, distinct status events for one message, repeated status\n   with a distinct event ID, out-of-order observations, unfamiliar event types,\n   fast acknowledgement, duplicate/conflict events causing no projection side\n   effects, invalid signatures creating no business-inbox row, trusted-route/header\n   endpoint mismatch rejection, temporary URL suspension/automatic resume observability, response handling,\n   and the chosen handoff. Do not call YCloud or deliver callbacks.\n\n## High-risk delete and secret rotation\n\nTreat delete and rotate-secret as high-risk external side effects. Stop before\nexecution, identify the target and impact, request explicit confirmation in a\nfuture approved workflow, and state rollback or cutover considerations only when\nconfirmed by the contract or project facts. Receiver code may support an\nexplicit candidate-secret list, but do not claim that a provider dual-secret\nwindow, old-secret validity period, atomic rotation, or recovery path exists.\nThe Skill never deletes endpoints, rotates secrets, or performs any other API\nmutation.\n\nSSRF controls belong to endpoint registration, not the receiver. For a project\nthat accepts callback URLs, propose scheme/port/redirect/DNS validation and\nreject private, loopback, link-local, and metadata addresses, including DNS\nrebinding checks. Treat IP allowlists and mTLS as project-dependent unless the\nprovider publishes stable support. Minimize raw payload retention; if required,\nencrypt it, restrict access, and use a reviewed retention period.\n\n## Outcome requirements\n\nAdapt the result to planning, implementation, or evaluation. Preserve these\ncontract and evidence outcomes:\n\n1. **Matched contract** — source hash, selected operation, exact path/method,\n   parameters, request/response schemas, and confirmed constraints.\n2. **Endpoint management plan** — placeholder raw HTTP or project-local\n   construction and the selected create/list/retrieve/update/delete/rotate branch.\n3. **Safety and boundary** — server-side credential placement, high-risk stop,\n   and explicit separation of endpoint management from receiver processing.\n4. **Tests** — synthetic contract and negative tests with no live endpoint/API.\n5. **CANNOT** — event-type fields not covered by a selected payload reference,\n   provider-fixed timestamp tolerance, provider retention, rotation\n   overlap/rollback,\n   unconfirmed SDK methods, missing project facts, unsupported operations, and\n   actions not run. Do not list the confirmed HMAC/retry/acknowledgement rules.\n6. **Handoff** — route message sending to `ycloud-whatsapp-messages`; return to\n   Architect with selected operation and `crosscutting:webhook-receiver` row\n   statuses, changed or proposed artifacts, tests/results, endpoint-to-receiver\n   boundary, unknowns, and outgoing handoffs. Select an event-specific payload\n   reference before mapping domain fields.\n\n## Non-goals\n\nThis Skill does not send messages, upload media, manage templates, read real\ncredentials, call YCloud, deliver a callback, or mutate production configuration.\nReceiver and endpoint client code may be implemented locally only when requested,\nmust use synthetic/no-network tests, and must state that no external operation\nwas performed.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}