Webhooks

On this page

Supported eventsCreating a webhookListing webhooksToggling a webhookDeleting a webhookVerifying signaturesTesting a webhookDelivery history

Receive HTTP notifications when events happen in your organization. Webhooks let you integrate fold.run with external systems — trigger CI pipelines on deploy, alert your team on errors, or log events to a monitoring service.

Supported events

Event Fires when
deploy.success A function is deployed successfully
deploy.failed A deployment fails
activation.error A function errors during execution
rollback.success A rollback completes
usage.threshold A usage alert threshold is exceeded

Creating a webhook

Create webhooks from the dashboard at app.fold.run/console/hooks. Click New webhook, select an event, enter your HTTPS URL, and optionally provide a signing secret.

Or via the CLI:

fold webhooks create deploy.success https://example.com/hook
Field Type Required Description
event string Yes One of the supported events above
url string Yes HTTPS URL to receive the webhook
secret string No HMAC secret for verifying webhook signatures

Listing webhooks

View your webhooks in the dashboard at app.fold.run/console/hooks, or via the CLI:

fold webhooks list

Toggling a webhook

Enable or disable a webhook from the dashboard — each webhook has a toggle switch.

Deleting a webhook

Delete a webhook from the dashboard, or via the CLI:

fold webhooks delete hook_abc123

Verifying signatures

If you provide a secret when creating the webhook, each delivery includes an HMAC signature you can verify:

import { createHmac } from "node:crypto";

function verifyWebhook(body: string, signature: string, secret: string) {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return signature === expected;
}

Testing a webhook

Test webhooks from the dashboard — each webhook in the table has an inline Test button. This sends a test payload to verify your endpoint is working.

Response:

{
  "success": true,
  "status": 200,
  "status_text": "OK"
}

If the request fails (timeout, connection refused, etc.):

{
  "success": false,
  "error": "Request timed out"
}

Delivery history

View recent deliveries for a webhook from the dashboard. Each webhook row has a History button that shows delivery status, event type, HTTP response code, attempt count, and response body.

Failed delivery queue (DLQ)

Webhook deliveries that fail after retries are placed in a dead letter queue. You can inspect failures and retry them.

DLQ statistics

curl "https://api.fold.run/webhook-deliveries/dlq/stats" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns counts of failed deliveries by event type and age.

List failed deliveries

curl "https://api.fold.run/webhook-deliveries/dlq" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns failed webhook deliveries with error details, attempt count, and timestamps.

Retry a failed delivery

curl -X POST "https://api.fold.run/webhook-deliveries/dlq/hook_abc123/retry" \
  -H "Authorization: Bearer YOUR_TOKEN"

Retries the failed webhook delivery. The delivery is removed from the DLQ on success.

Delivery API reference

Method Endpoint Description
GET /webhook-deliveries/dlq/stats DLQ statistics
GET /webhook-deliveries/dlq List failed deliveries
POST /webhook-deliveries/dlq/:webhook_id/retry Retry failed delivery

All webhook operations are also available via the fold CLI. See CLI for the full command reference.

PreviousSchedulesNextNotifications