Skip to main content
In a Native integration, your backend receives Refold webhooks to stay in sync with your customers’ connections and workflow runs. When a connection expires or a workflow errors, Refold POSTs the event to a URL you own, and you update your UI, retry, or alert from there. Webhooks are an org-level resource shared across Refold. The event catalog, subscription options, signature scheme, and retry behavior are documented once in Webhooks. This page covers wiring the handler into your Native backend.
Subscriptions are scoped per environment and registered with your API key (base URL https://app.refold.ai, header x-api-key). Register them with both your test and live keys.

​
Handle webhooks in your backend

1

Expose an HTTPS endpoint

Stand up a route (for example https://your-app.com/webhooks/refold) that accepts POST and returns 200 OK.
2

Subscribe to the events you need

Register the URL and events with Create Webhook, or in the Console under Developer > Webhooks. The events most Native backends use are Connection Expired (prompt a reconnect) and Workflow Errored (alert or retry). See the event catalog.
3

Verify the signature

Confirm each delivery came from Refold by checking the x-cobalt-signature header against an HMAC-SHA256 of the raw body keyed on your API key. See the verification code.
4

Acknowledge fast, then process

Return 200 OK immediately and do the slow work off the request path. A non-200 makes Refold retry (up to 3 times with exponential backoff).
Retries mean the same event can arrive more than once. Make handlers idempotent: key on instance_id for workflow events, or on the account and app for connection events.

​
See also

  • Webhooks: event catalog, subscription, signature verification, and retries
  • Connection status: act on a Connection Expired event
  • Events: send events into Refold to start workflows