Automations overview
Connect RefRef to Zapier, Make, or Activepieces with a signed webhook and one API call.
RefRef has no native app in Zapier, Make, or Activepieces. Each platform connects with a recipe: a webhook trigger that receives a RefRef event, a step that verifies its signature, and an HTTP step that calls the RefRef API.
The recipes on these pages grant a Reward and confirm it. The same shape works for every event type: subscribe to the type, verify the request, and act on data.
What was checked
Each recipe ran once, on 4 and 5 October 2026, against a local RefRef stack
through a temporary tunnel: a signed reward.earned event reached the
platform, the platform verified it, and its confirmation made the Reward
fulfilled. The recipes have not run against a hosted RefRef environment.
The flow
- RefRef sends a signed
reward.earnedevent to the platform's webhook URL. - The platform verifies the signature and stops the run if it fails.
- The platform grants the Reward in your product.
- The platform confirms the grant with
POST /v1/rewards/{rewardId}/fulfillment.
1. Create the trigger
Create the flow with the platform's webhook trigger and copy its URL. The trigger must keep the raw request body and the request headers, because the signature covers the exact bytes that RefRef sent. Each platform page names the trigger option to use.
2. Subscribe the URL
Subscribe the trigger URL with a Workspace API key. A Console admin can also add the endpoint in Developers → Webhooks.
curl -X POST "$REFREF_API/v1/webhook-endpoints" \
-H "x-api-key: $REFREF_API_KEY" \
-H "content-type: application/json" \
-d '{
"projectId": "prj_…",
"url": "https://hooks.example.com/…",
"eventTypes": ["reward.earned"],
"fulfillmentMode": "explicit"
}'The answer contains a secret that starts with whsec_. RefRef shows it only once. Keep it for the verify step.
Use fulfillmentMode: "explicit". An automation platform answers the webhook before its later steps run. With the default mode, on_delivery, that early answer would mark the Reward fulfilled before your product granted it. With explicit, the Reward stays pending until your flow confirms it.
3. Verify the signature
RefRef signs each request with Standard Webhooks headers:
| Header | Value |
|---|---|
webhook-id | The event ID. Every delivery of one event has the same ID. |
webhook-timestamp | Unix seconds when RefRef signed the request. |
webhook-signature | v1,<base64 HMAC-SHA256> of <webhook-id>.<webhook-timestamp>.<raw body>, space-separated |
The HMAC key is the base64-decoded text after whsec_. After a secret rotation, the header has one signature for each active secret, so accept the request when any one of them matches. Refuse a timestamp more than five minutes from your clock.
Verify before any other step, and stop the run when the check fails. Anyone who knows the trigger URL can send a request to it.
4. Grant the Reward
Grant the Reward in your product. Use the Reward ID (data.reward.id) as the idempotency key, because RefRef can deliver one event more than once.
5. Confirm the fulfillment
Call the API after the grant:
POST /v1/rewards/{rewardId}/fulfillment
x-api-key: <Workspace API key>
content-type: application/json
{ "projectId": "prj_…", "externalReference": "zapier:wev_…" }A repeat with the same facts returns the same record, so a retry is safe. Retry this step on a 5xx answer.
Delivery and retries
RefRef waits 10 seconds for an answer and follows no redirect. A 2xx answer ends the delivery. Any other answer, or a timeout, makes RefRef try again for about 72 hours. A Console admin sees each attempt and can replay a failed delivery.
Event types
| Type | When |
|---|---|
participant.created | A trusted call named a participant that was new |
referral.created | Attribution bound a referral |
event.recorded | RefRef recorded an Event and its attribution decision |
reward.earned | A participant earned a Reward |
reward.voided | An operator voided a Reward |
reward.fulfilled | A Reward was fulfilled |
reward.revoked | Your product took back a voided Reward |
payout.paid | A payout paid cash Rewards of the Project |
payout.failed | A payout failed before payment |
payout.returned | The provider returned a payout |
Every event has the envelope { id, type, apiVersion, occurredAt, projectId, environment, data }.
Keep credentials safe
The flow holds two credentials: the signing secret and a Workspace API key. Use the platform's credential store where it has one. Anyone who can edit a flow can read values typed into its steps, so limit edit access to the people who may hold the API key.