Skip to main content
POST
/
api
/
v2
/
public
/
webhook
curl -X POST "https://app.refold.ai/api/v2/public/webhook" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-app.com/webhooks",
    "webhook_events": ["Workflow Errored", "Connection Expired"],
    "webhook_type": "default"
  }'

{
  "_id": "6a313eda6d5528bdcf71ebac",
  "org_id": "6500a1b2c3d4e5f6a7b8c9d0",
  "environment": "test",
  "is_enabled": true,
  "webhook_events": ["Workflow Errored", "Connection Expired"],
  "workflow_ids": [],
  "webhook_url": "https://your-app.com/webhooks",
  "webhook_body": "{{event}}",
  "method": "POST",
  "webhook_type": "default",
  "createdAt": "2026-06-16T12:17:30.231Z",
  "updatedAt": "2026-06-16T12:17:30.231Z",
  "__v": 0
}
Register a webhook to receive real-time notifications when events occur in Refold — connection and workflow lifecycle events are pushed to your URL immediately, so you don’t have to poll.

​
Authentication

Webhooks are an org-level resource, so this endpoint uses API-key auth.
​
x-api-key
string
required
Your Refold API key. Find it in Settings → Credentials.

​
Body Parameters

​
webhook_url
string
required
HTTPS URL that will receive event POSTs. Must match ^https?://.
​
webhook_events
array
required
Event types to subscribe to (at least one):
  • Connection Created — a linked account connects an integration
  • Connection Deleted — a linked account disconnects an integration
  • Connection Expired — an integration’s authentication expires
  • Workflow Completed — a workflow execution succeeds
  • Workflow Errored — a workflow execution fails
​
webhook_type
string
default:"default"
Payload format: default, slack, or custom.
​
method
string
default:"POST"
HTTP method used to deliver the event: POST, PUT, or PATCH.
​
webhook_headers
object
Custom headers to send with each delivery.
​
webhook_body
any
Custom payload template. Defaults to {{event}} (the full event object).
​
slug
string
Restrict to a single app. When set, only workflow-type events are allowed.
​
workflow_ids
array
Restrict workflow events to specific workflow IDs.

​
Response

Returns the created webhook.
​
_id
string
Webhook ID.
​
org_id
string
Owning org.
​
environment
string
test or live.
​
is_enabled
boolean
Whether the webhook is active.
​
webhook_events
array
Subscribed events.
​
webhook_url
string
Delivery URL.
​
webhook_type
string
Payload format.
​
method
string
Delivery HTTP method.
​
webhook_body
string
Payload template.
​
workflow_ids
array
Restricted workflow IDs, if any.
​
createdAt
string
ISO 8601 timestamp.
{
  "_id": "6a313eda6d5528bdcf71ebac",
  "org_id": "6500a1b2c3d4e5f6a7b8c9d0",
  "environment": "test",
  "is_enabled": true,
  "webhook_events": ["Workflow Errored", "Connection Expired"],
  "workflow_ids": [],
  "webhook_url": "https://your-app.com/webhooks",
  "webhook_body": "{{event}}",
  "method": "POST",
  "webhook_type": "default",
  "createdAt": "2026-06-16T12:17:30.231Z",
  "updatedAt": "2026-06-16T12:17:30.231Z",
  "__v": 0
}

curl -X POST "https://app.refold.ai/api/v2/public/webhook" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-app.com/webhooks",
    "webhook_events": ["Workflow Errored", "Connection Expired"],
    "webhook_type": "default"
  }'