@convertrilo/sdk 0.0.5 → 0.0.7

package/README.md

@@ -167,6 +167,19 @@ for (const job of batch.jobs || []) {
 
 Poll each returned `jobId` with `client.onDemandStatus(jobId)`.
 
+## Webhook Delivery History
+
+Managed webhooks are HMAC signed. You can test a webhook and inspect recent delivery attempts:
+
+```ts
+await client.testWebhook(webhookId);
+
+const history = await client.getWebhookDeliveries(webhookId);
+for (const delivery of history.deliveries || []) {
+  console.log(delivery.status, delivery.statusCode, delivery.event);
+}
+```
+
 ## Regenerate Types
 
 The SDK types are generated from `openapi.yaml`.

package/dist/src/index.d.ts

@@ -115,8 +115,22 @@ export declare class ConvertriloClient {
         lastFailedAt?: string | null;
         createdAt?: string;
     }>;
+    updateWebhook(id: string, body: paths["/webhooks/{id}"]["patch"]["requestBody"]["content"]["application/json"]): Promise<{
+        id?: string;
+        url?: string;
+        events?: string[];
+        secret?: string;
+        isActive?: boolean;
+        failureCount?: number;
+        lastTriggeredAt?: string | null;
+        lastFailedAt?: string | null;
+        createdAt?: string;
+    }>;
     deleteWebhook(id: string): Promise<unknown>;
     testWebhook(id: string): Promise<unknown>;
+    getWebhookDeliveries(id: string): Promise<{
+        deliveries?: import("./types").components["schemas"]["WebhookDeliveryResponse"][];
+    }>;
     initStream(id: string): Promise<{
         ok?: boolean;
         uploadId?: string;

package/dist/src/index.js

@@ -134,12 +134,21 @@ export class ConvertriloClient {
             body: JSON.stringify(body),
         });
     }
+    async updateWebhook(id, body) {
+        return this.request(`/webhooks/${id}`, {
+            method: "PATCH",
+            body: JSON.stringify(body),
+        });
+    }
     async deleteWebhook(id) {
         return this.request(`/webhooks/${id}`, { method: "DELETE" });
     }
     async testWebhook(id) {
         return this.request(`/webhooks/${id}/test`, { method: "POST" });
     }
+    async getWebhookDeliveries(id) {
+        return this.request(`/webhooks/${id}/deliveries`);
+    }
     // Streaming
     async initStream(id) {
         return this.request(`/jobs/${id}/stream/init`, { method: "POST" });

package/dist/src/types.d.ts

@@ -707,6 +707,56 @@ export interface paths {
         };
         trace?: never;
     };
+    "/webhooks/{id}/deliveries": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List webhook delivery attempts
+         * @description Returns the 50 most recent managed or test delivery attempts for this webhook.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Recent delivery attempts */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["WebhookDeliveryListResponse"];
+                    };
+                };
+                /** @description Webhook not found */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/jobs/bulk": {
         parameters: {
             query?: never;
@@ -1655,6 +1705,33 @@ export interface components {
         WebhookListResponse: {
             webhooks?: components["schemas"]["WebhookResponse"][];
         };
+        WebhookDeliveryResponse: {
+            /** Format: uuid */
+            id?: string;
+            /** Format: uuid */
+            webhookId?: string;
+            event?: string;
+            /** Format: uuid */
+            jobId?: string | null;
+            /** @enum {string} */
+            status?: "success" | "failed";
+            statusCode?: number | null;
+            durationMs?: number | null;
+            /** @description Response body captured from the receiver, truncated to 2048 characters. */
+            responseBody?: string | null;
+            /** @description Network, timeout, or delivery error, truncated to 2048 characters. */
+            error?: string | null;
+            attempt?: number;
+            /** Format: date-time */
+            nextRetryAt?: string | null;
+            /** Format: date-time */
+            retriedAt?: string | null;
+            /** Format: date-time */
+            createdAt?: string;
+        };
+        WebhookDeliveryListResponse: {
+            deliveries?: components["schemas"]["WebhookDeliveryResponse"][];
+        };
         S3Output: {
             bucket: string;
             key: string;

package/docs/WEBHOOKS.md

@@ -127,7 +127,62 @@ export async function POST(req: NextRequest) {
 - A webhook is automatically disabled after 10 consecutive failures
 - Re-enable it with `PATCH /webhooks/{id}` and `{ "isActive": true }`
 
-Current deliveries are best-effort. There is not yet a durable retry queue or delivery history API.
+Failed managed deliveries are scheduled for retry when possible.
+
+Retry schedule:
+
+- Attempt 2: about 1 minute after the failed attempt
+- Attempt 3: about 5 minutes after the failed attempt
+- Attempt 4: about 30 minutes after the failed attempt
+
+Run due retries with:
+
+```bash
+pnpm run webhooks:retry
+```
+
+Use `--limit` to cap one run:
+
+```bash
+pnpm run webhooks:retry -- --limit=50
+```
+
+Schedule this command every minute in production. Webhooks are still disabled after
+10 consecutive failures.
+
+## Delivery History
+
+Recent managed and test delivery attempts are available with:
+
+```txt
+GET /webhooks/{id}/deliveries
+```
+
+The response includes the 50 most recent attempts for that webhook:
+
+```json
+{
+  "deliveries": [
+    {
+      "id": "550e8400-e29b-41d4-a716-446655440000",
+      "webhookId": "4a5c26a0-7b04-4d37-8bb1-446655440000",
+      "event": "job.completed",
+      "jobId": "9db109f6-6a88-49d7-89e2-446655440000",
+      "status": "success",
+      "statusCode": 204,
+      "durationMs": 182,
+      "responseBody": null,
+      "error": null,
+      "attempt": 1,
+      "nextRetryAt": null,
+      "retriedAt": null,
+      "createdAt": "2026-06-09T07:30:00.000Z"
+    }
+  ]
+}
+```
+
+`responseBody` and `error` are capped at 2048 characters.
 
 ## One-Off On-Demand Webhook URL
 

package/openapi.yaml

@@ -345,6 +345,35 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/WebhookResponse"
+    WebhookDeliveryResponse:
+      type: object
+      properties:
+        id: { type: string, format: uuid }
+        webhookId: { type: string, format: uuid }
+        event: { type: string }
+        jobId: { type: string, format: uuid, nullable: true }
+        status: { type: string, enum: [success, failed] }
+        statusCode: { type: integer, nullable: true }
+        durationMs: { type: integer, nullable: true }
+        responseBody:
+          type: string
+          nullable: true
+          description: Response body captured from the receiver, truncated to 2048 characters.
+        error:
+          type: string
+          nullable: true
+          description: Network, timeout, or delivery error, truncated to 2048 characters.
+        attempt: { type: integer }
+        nextRetryAt: { type: string, format: date-time, nullable: true }
+        retriedAt: { type: string, format: date-time, nullable: true }
+        createdAt: { type: string, format: date-time }
+    WebhookDeliveryListResponse:
+      type: object
+      properties:
+        deliveries:
+          type: array
+          items:
+            $ref: "#/components/schemas/WebhookDeliveryResponse"
 
     # On-Demand Encoding
     S3Output:
@@ -897,6 +926,29 @@ paths:
           schema: { type: string, format: uuid }
       responses:
         "200": { description: Test event sent }
+  /webhooks/{id}/deliveries:
+    get:
+      security: [{ BearerAuth: [] }]
+      summary: List webhook delivery attempts
+      description: Returns the 50 most recent managed or test delivery attempts for this webhook.
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "200":
+          description: Recent delivery attempts
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WebhookDeliveryListResponse"
+        "404":
+          description: Webhook not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
 
   /jobs/bulk:
     post:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@convertrilo/sdk",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "TypeScript client for the Convertrilo video encoding API",
   "private": false,
   "license": "MIT",