@t4h.framework/webhook 0.2.8 → 0.2.11

package/.ai/skills/framework-webhook/SKILL.md

@@ -1,134 +1,99 @@
 ---
 name: framework-webhook
 description: >-
-  Guides correct use of @t4h.framework/webhook in workflows: WebhookActivity,
-  the <<callbackUrl>> placeholder, callback auth (hmac/basic/header/bearer/jwt),
-  body schema, timeout, the partner's dispatch answer, and how hosts implement
-  the core GetActivityCallbackUrlClaim and the callbacks route. Use when a
-  workflow must wait for a third-party HTTP callback, when working in
-  packages/webhook, or when wiring a host (runtime or dev) for external advances.
+  Suspends a T4H Framework workflow until a third party calls back over HTTP,
+  with webhook() and WebhookActivity from @t4h.framework/webhook. Use when a
+  workflow must send a request to a partner and wait for its callback (payment
+  provider, document signing, long partner job), or when the user mentions the
+  <<callbackUrl>> placeholder, callback auth (hmac, basic, header, bearer, jwt,
+  jwks), a callback body schema, timeoutInMs, callback.dispatch,
+  { wait: false }, WebhookDispatchError or WebhookTimeoutError.
 ---
 
 # @t4h.framework/webhook
 
-Suspend a workflow until a third party calls back. Package path:
-`framework/packages/webhook`. Peer dependency: `@t4h.framework/core`.
+## Wait for a partner callback
 
-## Import surface
+1. Declare the callback credential with `type: Secret` in the `EnvDesign` in
+   `src/constants/environments.ts`. A token for the outbound
+   `request.headers` is `type: String`, because `headers` takes strings.
+2. Call `webhook()` in the workflow body. Put `<<callbackUrl>>` where the
+   partner expects the URL to call back.
+3. Read `callback.body` (typed by `schema`) and `callback.dispatch` (the
+   partner's answer to the request).
 
 ```typescript
-import { webhook, WebhookActivity } from '@t4h.framework/webhook'
-import type { AsyncActivityCallbackAuth } from '@t4h.framework/core'
-```
-
-## Workflow usage
+import { webhook } from '@t4h.framework/webhook'
+import Type from 'typebox'
 
-```typescript
 import { environments } from '../constants/environments.js'
 
 const callback = await webhook({
   request: {
     url: 'https://partner.example.com/jobs',
+    headers: { authorization: `Bearer ${environments.PARTNER_TOKEN}` },
     body: { json: { notifyUrl: '<<callbackUrl>>' } },
   },
-  auth: { type: 'hmac', secret: environments.WEBHOOK_SECRET, header: 'x-signature' },
+  auth: {
+    type: 'hmac',
+    secret: environments.PARTNER_WEBHOOK_SECRET,
+    header: 'x-hub-signature-256',
+    signaturePrefix: 'sha256=',
+  },
   schema: Type.Object({ status: Type.String() }),
-  timeoutInMs: 86_400_000,
+  timeoutInMs: 7 * 24 * 60 * 60 * 1000,
 })
 ```
 
-The credential fields of `auth` are typed `Secret` (core
-`AsyncActivityCallbackAuth.ts`). The host reads the value when it verifies a
-callback; the pending activity records the name, never the value.
-
-```typescript
-callback.dispatch?.body // the partner's answer to the request
-callback.body.status // the callback body, typed by schema
-```
-
-- `request` is optional (inbound only). Put `<<callbackUrl>>` anywhere in it.
-  It is sent during `bootstrap` through `HttpClientRequestClaim`; a network
-  error or status ≥ 400 rejects the activity at once.
-- `auth` is optional; the URL token alone is the credential without it.
-- `schema` is the schema of the callback **body**; the host validates it and
-  it types `callback.body`.
-- Rejections surface as errors from `await webhook()`: `WebhookDispatchError`
-  (`status?`, `message`) or `WebhookTimeoutError`. The stored output is
-  `{ reason: 'dispatch_failed', status?, message }` or `{ reason: 'timeout' }`.
-- `webhook(options, { wait: false })` sends the request and returns a
-  `WebhookHandle` instead of suspending; do other work, then
-  `await handle.wait()`.
-- The pending payload is only the partner's answer to the request. A workflow
-  that needs its own callback URL puts `<<callbackUrl>>` in the request body
-  and reads it back from `callback.dispatch`.
-
-## Auth cheat sheet
-
-- GitHub: `{ type: 'hmac', header: 'x-hub-signature-256', signaturePrefix: 'sha256=' }`
-- Shopify: `{ type: 'hmac', header: 'x-shopify-hmac-sha256', signatureFormat: 'base64' }`
-- Slack: `{ type: 'hmac', header: 'x-slack-signature', signaturePrefix: 'v0=', timestampHeader: 'x-slack-request-timestamp', toleranceInSeconds: 300, signedPayload: 'v0:{timestamp}:{body}' }`
-- Fixed credentials: `basic`, `header`, `bearer`
-- Google Pub/Sub push style: `{ type: 'jwt', jwksUri, issuer, audience }`
-
-## How it fits the core
-
-Every pending async activity can be advanced from outside through
-`POST .../activities/:activityId/callbacks?token=…`. `WebhookActivity` only
-adds the outbound request: `bootstrap` reads the URL from the core
-`GetActivityCallbackUrlClaim`, sends `request` with `HttpClientRequestClaim`,
-and returns `pending({ payload: dispatch, schema, auth, timeoutAt })`.
-`advance` receives the parsed body as payload, the bootstrap pending (for
-`dispatch`) and `{ method, headers }` as the third argument
-(`AsyncActivityAdvanceContext`).
-
-## Host contract
-
-The callbacks route belongs to the core and serves every async activity; the
-helpers below live in the `AsyncActivityCallback` namespace of `@t4h.framework/core`, not
-in this package.
-
-1. `GetActivityCallbackUrlClaim.getActivityCallbackUrl()`: absolute `http(s)`
-   URL of the current activity's callbacks route with
-   `?token=AsyncActivityCallback.deriveToken(secret, activityId)`. Nothing stored.
-2. Callback route: `AsyncActivityCallback.isTokenValid` **first** (404 if the token was
-   never minted) → activity/pending lookup (503 + `Retry-After` if the pending
-   is not visible yet: the partner called back before the tick committed) →
-   `AsyncActivityCallback.authorize(pending.auth, { method, headers, rawBody }, authorizers)`
-   (401) → advance with `AsyncActivityCallback.parseBody(contentType, rawBody)` and
-   `{ method, headers: AsyncActivityCallback.flattenHeaders(headers) }`. 410 when no longer pending,
-   202 otherwise (repeats included).
-3. `authorizers` is `{ hmac, jwt }` with the default exports of
-   `@t4h.framework/hmac/callback` and `@t4h.framework/jwks/callback`; `basic`,
-   `header` and `bearer` are built into the core. A declared type without an
-   authorizer throws `AsyncActivityCallbackAuthorizerMissingException`.
-4. Verification needs the **raw body**; parse JSON only after it.
-
-The dev server implements this in `packages/dev` (`DevGetActivityCallbackUrlClaim`,
-`CallbackTokenService`, `CallbackAuthorizersService`,
-`CreateWorkflowRunAsyncActivityPendingCallback`, route
-`POST /projects/:project/workflows/:workflow/runs/:run/activities/:activity/callbacks`).
-
-## Testing
+- Omit `request` when the partner already knows the URL (inbound only).
+- Pass `{ wait: false }` as the second argument to get a handle, do other
+  work, then `await handle.wait()`.
+- The fields of `auth` by type: `hmac` in **framework-hmac**, `jwt` and `jwks`
+  in **framework-jwks**. `basic`, `header` and `bearer` are built into the
+  core.
+
+## Traps
+
+- `auth` credentials (`secret`, `password`, `value`, `token`) are `Secret`s:
+  pass the `environments` entry whole. Do not read the value.
+- A value in `request.headers` is a plain string and goes into the history.
+- `schema` is the schema of the callback BODY, not of the dispatch answer. The
+  host refuses a body that does not match; your code never sees it.
+- `timeoutInMs` is milliseconds. Without it, the activity sets no timeout.
+- A dispatch with a network error or status 400 or more makes `webhook()`
+  throw `WebhookDispatchError` (`status`, `message`). No callback before the
+  timeout throws `WebhookTimeoutError`. Catch them in the workflow if the
+  workflow must continue.
+- The request body is `{ json }` or `{ text }`, not a raw object.
+  `method` defaults to `POST`.
+- `callback.headers` keys are lower case.
+- The host must provide `GetActivityCallbackUrlClaim` (core) and
+  `HttpClientRequestClaim` (`@t4h.framework/http`). An invalid callback URL
+  throws `WebhookCallbackUrlError`.
+- Partners cannot reach `localhost`. In development, use a local stub that
+  calls the `<<callbackUrl>>` it receives.
+
+## Test
+
+With `TestWorkflowEnvironment`, mock the activity like any async activity:
 
 ```typescript
-import { mockAsync, fulfilled } from '@t4h.framework/core/testing'
-
-mockAsync().on(
-  WebhookActivity,
-  fulfilled({ method: 'POST', headers: {}, body }),
-)
+import { fulfilled, mockAsync } from '@t4h.framework/core/testing'
+import { WebhookActivity } from '@t4h.framework/webhook'
+
+await env.execute(workflow, input, {
+  mockAsyncActivity: mockAsync().on(
+    WebhookActivity,
+    fulfilled({ method: 'POST', headers: {}, body: { status: 'signed' } }),
+  ),
+})
 ```
 
-Unit-test the activity with fake claims under `Claim.run`:
+See the **framework-workflow-testing** skill for the harness.
 
-```typescript
-Claim.run(
-  [
-    { provide: HttpClientRequestClaim, value: fakeHttpClaim },
-    { provide: GetActivityCallbackUrlClaim, value: fakeCallbackUrlClaim },
-  ],
-  () => activity.bootstrap(input),
-)
-```
+## Reference
 
-See the **framework-workflow-testing** skill for the full harness API.
+- Guide: <https://tech4humans-brasil.github.io/framework/webhook/>
+- Types: `node_modules/@t4h.framework/webhook/dist/webhook.d.ts`
+- Callback `auth` types: `AsyncActivityCallbackAuth` in
+  `node_modules/@t4h.framework/core/dist/`

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @t4h.framework/webhook
 
+## 0.2.11
+
+## 0.2.10
+
+## 0.2.9
+
+### Patch Changes
+
+- [#257](https://github.com/tech4humans-brasil/framework/pull/257) [`586bfb4`](https://github.com/tech4humans-brasil/framework/commit/586bfb4663f4a478527ee0c8db360603f034d615) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The webhook README is now short and links to the site. The site page now describes the outbound request body and the claims that the host must provide, and gives a 410 answer for a callback after the activity was advanced.
+
 ## 0.2.8
 
 ### Patch Changes

package/README.md

@@ -1,20 +1,16 @@
 # @t4h.framework/webhook
 
-Suspend a workflow until a third party calls back over HTTP.
+Suspend a T4H Framework workflow until a third party calls back over HTTP. The
+host verifies the callback before the workflow sees it.
 
-## Usage
-
-Declare the callback secret with `type: Secret` in the `EnvDesign` in `src/constants/environments.ts`:
+## Install
 
-```typescript
-// src/constants/environments.ts
-import { EnvDesign, Secret } from '@t4h.framework/core'
-
-export const environments = EnvDesign({
-  PARTNER_SECRET: { type: Secret },
-})
+```bash
+npm install @t4h.framework/webhook @t4h.framework/core @t4h.framework/http
 ```
 
+## Usage
+
 ```typescript
 import { webhook } from '@t4h.framework/webhook'
 import Type from 'typebox'
@@ -26,33 +22,21 @@ const callback = await webhook({
     url: 'https://partner.example.com/jobs',
     body: { json: { callback: '<<callbackUrl>>' } },
   },
-  auth: { type: 'hmac', secret: environments.PARTNER_SECRET, header: 'x-signature' },
+  auth: {
+    type: 'hmac',
+    secret: environments.PARTNER_SECRET,
+    header: 'x-signature',
+  },
   schema: Type.Object({ status: Type.String() }),
   timeoutInMs: 24 * 60 * 60 * 1000,
 })
 
-callback.dispatch?.body // what the partner answered to the request
-callback.body.status // typed by the schema
+callback.body.status
 ```
 
-Every pending activity already has a callback URL; `webhook()` sends
-`request` with the placeholder replaced by that URL and resumes the workflow
-when the partner posts to it. The callback must carry the token in the URL and
-pass the `auth` you declared; the body must match `schema`.
-
-A failed request throws `WebhookDispatchError` and a callback that never
-arrives before `timeoutInMs` throws `WebhookTimeoutError`, so the workflow
-never sees a callback that did not happen.
-
-Supported `auth`: `hmac` (GitHub, Shopify, Slack style), `basic`, `header`,
-`bearer`, `jwt` (bearer JWT verified with a JWKS) and `jwks` (detached
-signature verified with a JWKS key).
+Declare `PARTNER_SECRET` with `type: Secret` in the `EnvDesign` in
+`src/constants/environments.ts`.
 
-Pass `{ wait: false }` as the second argument to send the request without
-suspending; you get a handle and call `handle.wait()` later.
+## Documentation
 
-Hosts implement the core `GetActivityCallbackUrlClaim` and the callbacks
-route, both defined by `@t4h.framework/core` and shared by every async
-activity; the outbound request goes through `HttpClientRequestClaim` from
-`@t4h.framework/http`. Peer dependencies: `@t4h.framework/core` and
-`@t4h.framework/http`.
+<https://tech4humans-brasil.github.io/framework/webhook/>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/webhook",
-  "version": "0.2.8",
+  "version": "0.2.11",
   "description": "Webhook module for the T4H Framework",
   "homepage": "https://github.com/tech4humans-brasil/framework/tree/main/packages/webhook",
   "bugs": "https://github.com/tech4humans-brasil/framework/issues",
@@ -36,8 +36,8 @@
     "typebox": "^1.1.6"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.20.0",
-    "@t4h.framework/http": "^0.8.0",
+    "@t4h.framework/core": "^0.21.2",
+    "@t4h.framework/http": "^0.8.3",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },