Skip to main content
An event is a named signal your backend sends to Refold to start one or more workflows. You define an event once, attach workflows to it, then fire it from your app whenever the matching thing happens, for example a contact created or an invoice paid. Refold runs every workflow wired to that event, passing along the payload you send. Events decouple your app from the integrations behind them. One event can drive several workflows across several apps, so your backend fires a single signal and Refold fans it out.
Firing an event is account-scoped: it runs for one linked account. Authenticate with your API key and the linked_account_id, against the base URL https://app.refold.ai.

​
How it works

An event has a name and a sample payload. The sample payload defines the data fields a workflow can reference as variables. When you fire the event with real data, those fields fill the variables inside every attached workflow. The lifecycle is:
  • Define the event in the Console, with a sample payload that mirrors what you will send.
  • Attach workflows that should run when the event fires.
  • Fire the event from your backend with a real payload for a specific linked account.

​
Define an event

You create events in the Console before you can fire them.
1

Open the events page

In the Refold Console, go to Settings > Developer > Events.
2

Create the event

Click New Event, choose a model, and give it a name.
3

Set the sample payload

Edit the sample payload to match the data you will send. Each field becomes a variable workflows can use. Click Create event.
Workflows reference the event’s payload fields as trigger variables. Keep the sample payload’s field names stable, renaming a field can break workflows that reference it.

​
Fire an event

Fire the event from your backend for a specific linked account. The app slug goes in the URL path, and the body carries the event name and your payload.
cURL
curl -X POST "https://app.refold.ai/api/v2/public/event/hubspot" \
  -H "x-api-key: $REFOLD_API_KEY" \
  -H "linked_account_id: user_12345" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "New Contact Created",
    "payload": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com"
    }
  }'
Output
{
  "message": "Webhook Fired Success"
}
With the Node.js SDK, use event:
Node.js
const result = await client.event({
  linked_account_id: "user_12345",
  event: "New Contact Created",
  slug: "hubspot",
  payload: {
    first_name: "Jane",
    last_name: "Doe",
    email: "jane@example.com",
  },
});

console.log(result.message); // "Webhook Fired Success"
The slug (or path slug) narrows execution to one app’s workflows. Omit it to run every workflow attached to the event for that linked account.
The event name in the body must match the event name in the Console exactly, including case. A mismatch returns 404 INVALID_EVENT with “Trigger not found”.

​
Events vs webhooks

Both involve event payloads, but they move in opposite directions. Don’t confuse them.
EventsWebhooks
DirectionYour backend to RefoldRefold to your backend
PurposeStart a workflowReact to something that happened
You provideThe payload to run onAn endpoint to receive deliveries

​
Next steps

Build a workflow

Attach workflows to the events you fire.

Trigger event API

Full request and response reference.

Receive webhooks

Get notified when those workflows complete or error.

Node.js SDK

The event method and the rest of the server API.