Webhooks

Embed

<a href="https://referalli.com/docs/ref-webhooks"><img src="https://referalli.com/docs/_api/public/orgs/07f432f4-34b9-46a7-aaad-c0e395d2e4f9/spaces/2bf4f614-3630-4fbf-85f9-5ecafa6b7d97/pages/058fb54a-fa0d-45c0-b9ae-fe605071155a/social-card.svg?v=3e7ae33eec8b" alt="Webhooks" width="600" height="315"></a>

GEThttps://referalli.com/v1/webhook-endpoints

List webhook endpoints

Endpoints with their topics, programs, status (active, paused, disabled), secret-rotation state and failure state. Secrets are never returned.

Auth: an API key with webhooks:read (or full), or a session of any role.

Parameters

limitintegerquery

Items per page, 1 to 100 (default 50). From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

= 50

starting_afterstringquery

A cursor: the id of an item (the previous page's next_cursor); returns the items after it. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

ending_beforestringquery

A cursor: returns the items before this item id (the previous page). Not with starting_after. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

created[gte]stringquery

Only items created at or after this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

created[lte]stringquery

Only items created at or before this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

referalli-versionstringheader

The API version to run the request under (2026-10-21, 2026-11-01). Default: the API key's pinned version, else 2026-10-21. The header name from before the rename is still accepted; this name wins when both are sent.

2026-10-21 | 2026-11-01

x-org-idstringheader

With a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.

referalli-modestringheader

test runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.

live | test

Code samples

cURL

curl -X GET "https://referalli.com/v1/webhook-endpoints?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=" \
  -H "referalli-version: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/webhook-endpoints?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=', {
  method: 'GET',
  headers: {
    'referalli-version': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "GET",
    "https://referalli.com/v1/webhook-endpoints?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=",
    headers={
    "referalli-version": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/v1/webhook-endpoints?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=", nil)
	req.Header.Set("referalli-version", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/webhook-endpoints?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['referalli-version: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/webhook-endpoints?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=')
req = Net::HTTP::Get.new(uri)
req['referalli-version'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://referalli.com/v1/webhook-endpoints?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D="))
    .header("referalli-version", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 A page of the list. Under API version 2026-10-21 the body is the plain array instead.

Example

{
  "object": "string",
  "data": [
    {
      "id": "string",
      "url": "string",
      "topics": [
        "string"
      ],
      "programIds": [
        null
      ],
      "status": "active",
      "legacySignature": true,
      "rotation": {
        "inProgress": true,
        "previousSecretExpiresAt": "2024-01-01T00:00:00Z"
      },
      "failingSince": "2024-01-01T00:00:00Z",
      "disabledAt": "2024-01-01T00:00:00Z",
      "disabledReason": "string",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

Schema

objectstringrequired

dataWebhookEndpoint[]required

Show child parameters

idstringrequired

urlstringrequired

topicsstring[]required

programIdsstring[]required

null: every program. Otherwise only events about these programs (org-wide events such as payouts are not sent).

statusstringrequired

active | paused | disabled

legacySignaturebooleanrequired

Also send the deprecated body-only legacy signature header.

rotationobjectrequired

Show child parameters

inProgressbooleanrequired

previousSecretExpiresAtstring

failingSincestringrequired

When the current run of failed deliveries began.

disabledAtstringrequired

disabledReasonstringrequired

createdAtstringrequired

has_morebooleanrequired

Whether another page follows; pass next_cursor as starting_after to get it.

next_cursorstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

401 Missing or invalid credentials. error.code is one of:

Example

{
  "error": {
    "code": "unauthorized",
    "message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
    "docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

403 Authenticated, but not allowed. error.code is one of:

Example

{
  "error": {
    "code": "forbidden",
    "message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
    "docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

404 No such resource. error.code is one of:

Example

{
  "error": {
    "code": "not_found",
    "message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
    "docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

429 Rate limited. error.code is one of:

Example

{
  "error": {
    "code": "rate_limited",
    "message": "an endpoint limit or the per-key quota was exceeded",
    "docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

500 Unexpected server error. error.code is one of:

Example

{
  "error": {
    "code": "internal_error",
    "message": "retry with backoff",
    "requestId": "req_8f2c1d4e5a6b7c8d",
    "docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

default Any other error, in the same envelope.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "requestId": "string",
    "docs_url": "string"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

POSThttps://referalli.com/v1/webhook-endpoints

Create a webhook endpoint

Subscribes an HTTPS URL to event topics (default ["*"], every event; see the webhooks section of this document for each topic's payload). programIds limits it to events about those programs (org-wide events such as payouts are then not sent). Deliveries are signed the Standard Webhooks way with the returned secret (whsec_…), shown only here. legacySignature: true also sends the deprecated body-only signature.

Auth: an API key with webhooks:write (or full), or a session with role owner, admin.

Parameters

Idempotency-Keystringheader

Any unique string up to 255 printable ASCII characters (a UUID). A retry with the same key within 24 hours gets the first response again (with idempotent-replayed: true) and nothing runs twice. The same key on a different request is 422 idempotency_key_reused; while the first is still running, 409 idempotency_in_progress.

x-org-idstringheader

With a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.

referalli-modestringheader

test runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.

live | test

Request body application/json

urlstringrequired

topicsstring[]

= ["*"]

legacySignatureboolean

= false

programIdsstring[]

{
  "url": "string",
  "topics": [
    "*"
  ],
  "legacySignature": false,
  "programIds": [
    "string"
  ]
}

Code samples

cURL

curl -X POST "https://referalli.com/v1/webhook-endpoints" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: application/json" \
  -d '{"url":"string","topics":["*"],"legacySignature":false,"programIds":["string"]}'

TypeScript

const res = await fetch('https://referalli.com/v1/webhook-endpoints', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"url":"string","topics":["*"],"legacySignature":false,"programIds":["string"]}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/webhook-endpoints",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "application/json",
    },
    json={"url": "string", "topics": ["*"], "legacySignature": False, "programIds": ["string"]},
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/webhook-endpoints", strings.NewReader(`{"url":"string","topics":["*"],"legacySignature":false,"programIds":["string"]}`))
	req.Header.Set("Idempotency-Key", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/webhook-endpoints');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"url":"string","topics":["*"],"legacySignature":false,"programIds":["string"]}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/webhook-endpoints')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"url":"string","topics":["*"],"legacySignature":false,"programIds":["string"]}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://referalli.com/v1/webhook-endpoints"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"url\":\"string\",\"topics\":[\"*\"],\"legacySignature\":false,\"programIds\":[\"string\"]}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "id": "string",
  "url": "string",
  "topics": [
    "string"
  ],
  "programIds": [
    "string"
  ],
  "legacySignature": true,
  "secret": "string"
}

Schema

idstringrequired

urlstringrequired

topicsstring[]required

programIdsstring[]required

legacySignaturebooleanrequired

secretstringrequired

Returned only here. whsec_ + base64 key (Standard Webhooks).

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

401 Missing or invalid credentials. error.code is one of:

Example

{
  "error": {
    "code": "unauthorized",
    "message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
    "docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

403 Authenticated, but not allowed. error.code is one of:

Example

{
  "error": {
    "code": "forbidden",
    "message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
    "docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

404 No such resource. error.code is one of:

Example

{
  "error": {
    "code": "not_found",
    "message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
    "docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

409 The request conflicts with the current state. error.code is one of:

Example

{
  "error": {
    "code": "conflict",
    "message": "a unique value is taken, or the action would break a rule (the message says which)",
    "docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

422 The request cannot be processed as sent. error.code is one of:

Example

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "the `idempotency-key` was used for a different request",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

429 Rate limited. error.code is one of:

Example

{
  "error": {
    "code": "rate_limited",
    "message": "an endpoint limit or the per-key quota was exceeded",
    "docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

500 Unexpected server error. error.code is one of:

Example

{
  "error": {
    "code": "internal_error",
    "message": "retry with backoff",
    "requestId": "req_8f2c1d4e5a6b7c8d",
    "docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

default Any other error, in the same envelope.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "requestId": "string",
    "docs_url": "string"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

GEThttps://referalli.com/v1/webhook-endpoints/{id}

Get a webhook endpoint

One endpoint with its status, rotation and failure state.

Auth: an API key with webhooks:read (or full), or a session of any role.

Parameters

idstringpathrequired

x-org-idstringheader

With a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.

referalli-modestringheader

test runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.

live | test

Code samples

cURL

curl -X GET "https://referalli.com/v1/webhook-endpoints/{id}" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/webhook-endpoints/{id}', {
  method: 'GET',
  headers: {
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "GET",
    "https://referalli.com/v1/webhook-endpoints/{id}",
    headers={
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/v1/webhook-endpoints/{id}", nil)
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/webhook-endpoints/{id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/webhook-endpoints/{id}')
req = Net::HTTP::Get.new(uri)
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://referalli.com/v1/webhook-endpoints/{id}"))
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "id": "string",
  "url": "string",
  "topics": [
    "string"
  ],
  "programIds": [
    "string"
  ],
  "status": "active",
  "legacySignature": true,
  "rotation": {
    "inProgress": true,
    "previousSecretExpiresAt": "2024-01-01T00:00:00Z"
  },
  "failingSince": "2024-01-01T00:00:00Z",
  "disabledAt": "2024-01-01T00:00:00Z",
  "disabledReason": "string",
  "createdAt": "2024-01-01T00:00:00Z"
}

Schema

idstringrequired

urlstringrequired

topicsstring[]required

programIdsstring[]required

null: every program. Otherwise only events about these programs (org-wide events such as payouts are not sent).

statusstringrequired

active | paused | disabled

legacySignaturebooleanrequired

Also send the deprecated body-only legacy signature header.

rotationobjectrequired

Show child parameters

inProgressbooleanrequired

previousSecretExpiresAtstring

failingSincestringrequired

When the current run of failed deliveries began.

disabledAtstringrequired

disabledReasonstringrequired

createdAtstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

401 Missing or invalid credentials. error.code is one of:

Example

{
  "error": {
    "code": "unauthorized",
    "message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
    "docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

403 Authenticated, but not allowed. error.code is one of:

Example

{
  "error": {
    "code": "forbidden",
    "message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
    "docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

404 No such resource. error.code is one of:

Example

{
  "error": {
    "code": "not_found",
    "message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
    "docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

429 Rate limited. error.code is one of:

Example

{
  "error": {
    "code": "rate_limited",
    "message": "an endpoint limit or the per-key quota was exceeded",
    "docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

500 Unexpected server error. error.code is one of:

Example

{
  "error": {
    "code": "internal_error",
    "message": "retry with backoff",
    "requestId": "req_8f2c1d4e5a6b7c8d",
    "docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

default Any other error, in the same envelope.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "requestId": "string",
    "docs_url": "string"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

DELETEhttps://referalli.com/v1/webhook-endpoints/{id}

Delete a webhook endpoint

Removes the endpoint and its delivery history. Audited.

Auth: an API key with webhooks:write (or full), or a session with role owner, admin.

Parameters

idstringpathrequired

Idempotency-Keystringheader

x-org-idstringheader

With a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.

referalli-modestringheader

test runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.

live | test

Code samples

cURL

curl -X DELETE "https://referalli.com/v1/webhook-endpoints/{id}" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/webhook-endpoints/{id}', {
  method: 'DELETE',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "DELETE",
    "https://referalli.com/v1/webhook-endpoints/{id}",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("DELETE", "https://referalli.com/v1/webhook-endpoints/{id}", nil)
	req.Header.Set("Idempotency-Key", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/webhook-endpoints/{id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/webhook-endpoints/{id}')
req = Net::HTTP::Delete.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://referalli.com/v1/webhook-endpoints/{id}"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .method("DELETE", BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "ok": true
}

Schema

okbooleanrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

401 Missing or invalid credentials. error.code is one of:

Example

{
  "error": {
    "code": "unauthorized",
    "message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
    "docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

403 Authenticated, but not allowed. error.code is one of:

Example

{
  "error": {
    "code": "forbidden",
    "message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
    "docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

404 No such resource. error.code is one of:

Example

{
  "error": {
    "code": "not_found",
    "message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
    "docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

409 The request conflicts with the current state. error.code is one of:

Example

{
  "error": {
    "code": "conflict",
    "message": "a unique value is taken, or the action would break a rule (the message says which)",
    "docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

422 The request cannot be processed as sent. error.code is one of:

Example

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "the `idempotency-key` was used for a different request",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

429 Rate limited. error.code is one of:

Example

{
  "error": {
    "code": "rate_limited",
    "message": "an endpoint limit or the per-key quota was exceeded",
    "docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

500 Unexpected server error. error.code is one of:

Example

{
  "error": {
    "code": "internal_error",
    "message": "retry with backoff",
    "requestId": "req_8f2c1d4e5a6b7c8d",
    "docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

default Any other error, in the same envelope.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "requestId": "string",
    "docs_url": "string"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

PATCHhttps://referalli.com/v1/webhook-endpoints/{id}

Update a webhook endpoint

Changes the URL, topics, programs (null or [] for every program) or legacy signature, or pauses it (status: "paused", deliveries held). Setting active re-enables a paused or auto-disabled endpoint: held deliveries resume and the failure clock starts over. Audited.

Auth: an API key with webhooks:write (or full), or a session with role owner, admin.

Parameters

idstringpathrequired

Idempotency-Keystringheader

x-org-idstringheader

With a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.

referalli-modestringheader

test runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.

live | test

Request body application/json

statusstring

active | paused

urlstring

topicsstring[]

legacySignatureboolean

programIdsstring[]

{
  "status": "active",
  "url": "string",
  "topics": [
    "string"
  ],
  "legacySignature": true,
  "programIds": [
    "string"
  ]
}

Code samples

cURL

curl -X PATCH "https://referalli.com/v1/webhook-endpoints/{id}" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: application/json" \
  -d '{"status":"active","url":"string","topics":["string"],"legacySignature":true,"programIds":["string"]}'

TypeScript

const res = await fetch('https://referalli.com/v1/webhook-endpoints/{id}', {
  method: 'PATCH',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"status":"active","url":"string","topics":["string"],"legacySignature":true,"programIds":["string"]}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "PATCH",
    "https://referalli.com/v1/webhook-endpoints/{id}",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "application/json",
    },
    json={"status": "active", "url": "string", "topics": ["string"], "legacySignature": True, "programIds": ["string"]},
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	req, _ := http.NewRequest("PATCH", "https://referalli.com/v1/webhook-endpoints/{id}", strings.NewReader(`{"status":"active","url":"string","topics":["string"],"legacySignature":true,"programIds":["string"]}`))
	req.Header.Set("Idempotency-Key", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/webhook-endpoints/{id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"status":"active","url":"string","topics":["string"],"legacySignature":true,"programIds":["string"]}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/webhook-endpoints/{id}')
req = Net::HTTP::Patch.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"status":"active","url":"string","topics":["string"],"legacySignature":true,"programIds":["string"]}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://referalli.com/v1/webhook-endpoints/{id}"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "application/json")
    .method("PATCH", BodyPublishers.ofString("{\"status\":\"active\",\"url\":\"string\",\"topics\":[\"string\"],\"legacySignature\":true,\"programIds\":[\"string\"]}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "id": "string",
  "url": "string",
  "topics": [
    "string"
  ],
  "programIds": [
    "string"
  ],
  "status": "active",
  "legacySignature": true,
  "rotation": {
    "inProgress": true,
    "previousSecretExpiresAt": "2024-01-01T00:00:00Z"
  },
  "failingSince": "2024-01-01T00:00:00Z",
  "disabledAt": "2024-01-01T00:00:00Z",
  "disabledReason": "string",
  "createdAt": "2024-01-01T00:00:00Z"
}

Schema

idstringrequired

urlstringrequired

topicsstring[]required

programIdsstring[]required

null: every program. Otherwise only events about these programs (org-wide events such as payouts are not sent).

statusstringrequired

active | paused | disabled

legacySignaturebooleanrequired

Also send the deprecated body-only legacy signature header.

rotationobjectrequired

Show child parameters

inProgressbooleanrequired

previousSecretExpiresAtstring

failingSincestringrequired

When the current run of failed deliveries began.

disabledAtstringrequired

disabledReasonstringrequired

createdAtstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

401 Missing or invalid credentials. error.code is one of:

Example

{
  "error": {
    "code": "unauthorized",
    "message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
    "docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

403 Authenticated, but not allowed. error.code is one of:

Example

{
  "error": {
    "code": "forbidden",
    "message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
    "docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

404 No such resource. error.code is one of:

Example

{
  "error": {
    "code": "not_found",
    "message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
    "docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

409 The request conflicts with the current state. error.code is one of:

Example

{
  "error": {
    "code": "conflict",
    "message": "a unique value is taken, or the action would break a rule (the message says which)",
    "docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

422 The request cannot be processed as sent. error.code is one of:

Example

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "the `idempotency-key` was used for a different request",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

429 Rate limited. error.code is one of:

Example

{
  "error": {
    "code": "rate_limited",
    "message": "an endpoint limit or the per-key quota was exceeded",
    "docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

500 Unexpected server error. error.code is one of:

Example

{
  "error": {
    "code": "internal_error",
    "message": "retry with backoff",
    "requestId": "req_8f2c1d4e5a6b7c8d",
    "docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

default Any other error, in the same envelope.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "requestId": "string",
    "docs_url": "string"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

POSThttps://referalli.com/v1/webhook-endpoints/{id}/rotate-secret

Rotate an endpoint secret

Issues a new signing secret, returned once. For 24 hours (previousSecretExpiresAt) every delivery carries a signature from each secret, so receivers can switch without dropping any. Audited.

Auth: an API key with webhooks:write (or full), or a session with role owner, admin.

Parameters

idstringpathrequired

Idempotency-Keystringheader

x-org-idstringheader

With a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.

referalli-modestringheader

test runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.

live | test

Code samples

cURL

curl -X POST "https://referalli.com/v1/webhook-endpoints/{id}/rotate-secret" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/webhook-endpoints/{id}/rotate-secret', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/webhook-endpoints/{id}/rotate-secret",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/webhook-endpoints/{id}/rotate-secret", nil)
	req.Header.Set("Idempotency-Key", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/webhook-endpoints/{id}/rotate-secret');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/webhook-endpoints/{id}/rotate-secret')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://referalli.com/v1/webhook-endpoints/{id}/rotate-secret"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .method("POST", BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "id": "string",
  "secret": "string",
  "previousSecretExpiresAt": "2024-01-01T00:00:00Z"
}

Schema

idstringrequired

secretstringrequired

The new secret, shown once. The old one keeps signing until previousSecretExpiresAt.

previousSecretExpiresAtstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

401 Missing or invalid credentials. error.code is one of:

Example

{
  "error": {
    "code": "unauthorized",
    "message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
    "docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

403 Authenticated, but not allowed. error.code is one of:

Example

{
  "error": {
    "code": "forbidden",
    "message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
    "docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

404 No such resource. error.code is one of:

Example

{
  "error": {
    "code": "not_found",
    "message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
    "docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

409 The request conflicts with the current state. error.code is one of:

Example

{
  "error": {
    "code": "conflict",
    "message": "a unique value is taken, or the action would break a rule (the message says which)",
    "docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

422 The request cannot be processed as sent. error.code is one of:

Example

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "the `idempotency-key` was used for a different request",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

429 Rate limited. error.code is one of:

Example

{
  "error": {
    "code": "rate_limited",
    "message": "an endpoint limit or the per-key quota was exceeded",
    "docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

500 Unexpected server error. error.code is one of:

Example

{
  "error": {
    "code": "internal_error",
    "message": "retry with backoff",
    "requestId": "req_8f2c1d4e5a6b7c8d",
    "docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

default Any other error, in the same envelope.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "requestId": "string",
    "docs_url": "string"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

GEThttps://referalli.com/v1/webhook-deliveries

List webhook deliveries

Deliveries to every endpoint, newest first: topic, status (pending, delivered, failed), attempts, the last response code and, while pending, when the next attempt is. Filter with endpointId.

Auth: an API key with webhooks:read (or full), or a session of any role.

Parameters

endpointIdstringquery

Only deliveries to this endpoint.

limitintegerquery

Items per page, 1 to 100 (default 50). From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

= 50

starting_afterstringquery

A cursor: the id of an item (the previous page's next_cursor); returns the items after it. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

ending_beforestringquery

A cursor: returns the items before this item id (the previous page). Not with starting_after. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

created[gte]stringquery

Only items created at or after this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

created[lte]stringquery

Only items created at or before this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

referalli-versionstringheader

2026-10-21 | 2026-11-01

x-org-idstringheader

With a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.

referalli-modestringheader

test runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.

live | test

Code samples

cURL

curl -X GET "https://referalli.com/v1/webhook-deliveries?endpointId=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=" \
  -H "referalli-version: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/webhook-deliveries?endpointId=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=', {
  method: 'GET',
  headers: {
    'referalli-version': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "GET",
    "https://referalli.com/v1/webhook-deliveries?endpointId=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=",
    headers={
    "referalli-version": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/v1/webhook-deliveries?endpointId=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=", nil)
	req.Header.Set("referalli-version", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/webhook-deliveries?endpointId=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['referalli-version: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/webhook-deliveries?endpointId=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=')
req = Net::HTTP::Get.new(uri)
req['referalli-version'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://referalli.com/v1/webhook-deliveries?endpointId=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D="))
    .header("referalli-version", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 A page of the list. Under API version 2026-10-21 the body is the plain array instead.

Example

{
  "object": "string",
  "data": [
    {
      "id": "string",
      "endpointId": "string",
      "topic": "string",
      "status": "string",
      "attempts": 0,
      "lastStatusCode": 0,
      "lastAttemptAt": "2024-01-01T00:00:00Z",
      "nextAt": "2024-01-01T00:00:00Z",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

Schema

objectstringrequired

dataWebhookDelivery[]required

Show child parameters

idstringrequired

endpointIdstringrequired

topicstringrequired

statusstringrequired

attemptsintegerrequired

lastStatusCodeintegerrequired

lastAttemptAtstringrequired

nextAtstringrequired

When a pending delivery is next tried; null once settled.

createdAtstringrequired

has_morebooleanrequired

Whether another page follows; pass next_cursor as starting_after to get it.

next_cursorstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

401 Missing or invalid credentials. error.code is one of:

Example

{
  "error": {
    "code": "unauthorized",
    "message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
    "docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

403 Authenticated, but not allowed. error.code is one of:

Example

{
  "error": {
    "code": "forbidden",
    "message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
    "docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

404 No such resource. error.code is one of:

Example

{
  "error": {
    "code": "not_found",
    "message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
    "docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

429 Rate limited. error.code is one of:

Example

{
  "error": {
    "code": "rate_limited",
    "message": "an endpoint limit or the per-key quota was exceeded",
    "docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

500 Unexpected server error. error.code is one of:

Example

{
  "error": {
    "code": "internal_error",
    "message": "retry with backoff",
    "requestId": "req_8f2c1d4e5a6b7c8d",
    "docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

default Any other error, in the same envelope.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "requestId": "string",
    "docs_url": "string"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

GEThttps://referalli.com/v1/webhook-endpoints/{id}/deliveries

List an endpoint's deliveries

What one endpoint was sent, newest first.

Auth: an API key with webhooks:read (or full), or a session of any role.

Parameters

idstringpathrequired

limitintegerquery

Items per page, 1 to 100 (default 50). From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

= 50

starting_afterstringquery

A cursor: the id of an item (the previous page's next_cursor); returns the items after it. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

ending_beforestringquery

A cursor: returns the items before this item id (the previous page). Not with starting_after. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

created[gte]stringquery

Only items created at or after this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

created[lte]stringquery

Only items created at or before this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

referalli-versionstringheader

2026-10-21 | 2026-11-01

x-org-idstringheader

With a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.

referalli-modestringheader

test runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.

live | test

Code samples

cURL

curl -X GET "https://referalli.com/v1/webhook-endpoints/{id}/deliveries?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=" \
  -H "referalli-version: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/webhook-endpoints/{id}/deliveries?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=', {
  method: 'GET',
  headers: {
    'referalli-version': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "GET",
    "https://referalli.com/v1/webhook-endpoints/{id}/deliveries?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=",
    headers={
    "referalli-version": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/v1/webhook-endpoints/{id}/deliveries?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=", nil)
	req.Header.Set("referalli-version", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/webhook-endpoints/{id}/deliveries?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['referalli-version: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/webhook-endpoints/{id}/deliveries?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=')
req = Net::HTTP::Get.new(uri)
req['referalli-version'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://referalli.com/v1/webhook-endpoints/{id}/deliveries?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D="))
    .header("referalli-version", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 A page of the list. Under API version 2026-10-21 the body is the plain array instead.

Example

{
  "object": "string",
  "data": [
    {
      "id": "string",
      "endpointId": "string",
      "topic": "string",
      "status": "string",
      "attempts": 0,
      "lastStatusCode": 0,
      "lastAttemptAt": "2024-01-01T00:00:00Z",
      "nextAt": "2024-01-01T00:00:00Z",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

Schema

objectstringrequired

dataWebhookDelivery[]required

Show child parameters

idstringrequired

endpointIdstringrequired

topicstringrequired

statusstringrequired

attemptsintegerrequired

lastStatusCodeintegerrequired

lastAttemptAtstringrequired

nextAtstringrequired

When a pending delivery is next tried; null once settled.

createdAtstringrequired

has_morebooleanrequired

Whether another page follows; pass next_cursor as starting_after to get it.

next_cursorstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

401 Missing or invalid credentials. error.code is one of:

Example

{
  "error": {
    "code": "unauthorized",
    "message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
    "docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

403 Authenticated, but not allowed. error.code is one of:

Example

{
  "error": {
    "code": "forbidden",
    "message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
    "docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

404 No such resource. error.code is one of:

Example

{
  "error": {
    "code": "not_found",
    "message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
    "docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

429 Rate limited. error.code is one of:

Example

{
  "error": {
    "code": "rate_limited",
    "message": "an endpoint limit or the per-key quota was exceeded",
    "docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

500 Unexpected server error. error.code is one of:

Example

{
  "error": {
    "code": "internal_error",
    "message": "retry with backoff",
    "requestId": "req_8f2c1d4e5a6b7c8d",
    "docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

default Any other error, in the same envelope.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "requestId": "string",
    "docs_url": "string"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

GEThttps://referalli.com/v1/webhook-deliveries/{id}

Get a webhook delivery

One delivery in full: the exact payload sent, its eventId, and what the endpoint answered last (lastStatusCode, the first 2,000 characters of lastResponseBody, or lastError when there was no response).

Auth: an API key with webhooks:read (or full), or a session of any role.

Parameters

idstringpathrequired

x-org-idstringheader

With a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.

referalli-modestringheader

test runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.

live | test

Code samples

cURL

curl -X GET "https://referalli.com/v1/webhook-deliveries/{id}" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/webhook-deliveries/{id}', {
  method: 'GET',
  headers: {
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "GET",
    "https://referalli.com/v1/webhook-deliveries/{id}",
    headers={
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/v1/webhook-deliveries/{id}", nil)
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/webhook-deliveries/{id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/webhook-deliveries/{id}')
req = Net::HTTP::Get.new(uri)
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://referalli.com/v1/webhook-deliveries/{id}"))
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "id": "string",
  "endpointId": "string",
  "topic": "string",
  "status": "string",
  "attempts": 0,
  "lastStatusCode": 0,
  "lastAttemptAt": "2024-01-01T00:00:00Z",
  "nextAt": "2024-01-01T00:00:00Z",
  "createdAt": "2024-01-01T00:00:00Z",
  "eventId": "string",
  "payload": {},
  "lastResponseBody": "string",
  "lastError": "string"
}

Schema

idstringrequired

endpointIdstringrequired

topicstringrequired

statusstringrequired

attemptsintegerrequired

lastStatusCodeintegerrequired

lastAttemptAtstringrequired

nextAtstringrequired

When a pending delivery is next tried; null once settled.

createdAtstringrequired

eventIdstringrequired

payloadobjectrequired

Exactly what was sent (the delivery body).

lastResponseBodystringrequired

The start of the endpoint's last response (up to 2,000 characters).

lastErrorstringrequired

The network error of the last attempt, when there was no response.

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

401 Missing or invalid credentials. error.code is one of:

Example

{
  "error": {
    "code": "unauthorized",
    "message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
    "docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

403 Authenticated, but not allowed. error.code is one of:

Example

{
  "error": {
    "code": "forbidden",
    "message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
    "docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

404 No such resource. error.code is one of:

Example

{
  "error": {
    "code": "not_found",
    "message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
    "docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

429 Rate limited. error.code is one of:

Example

{
  "error": {
    "code": "rate_limited",
    "message": "an endpoint limit or the per-key quota was exceeded",
    "docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

500 Unexpected server error. error.code is one of:

Example

{
  "error": {
    "code": "internal_error",
    "message": "retry with backoff",
    "requestId": "req_8f2c1d4e5a6b7c8d",
    "docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

default Any other error, in the same envelope.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "requestId": "string",
    "docs_url": "string"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

POSThttps://referalli.com/v1/webhook-deliveries/{id}/replay

Replay a webhook delivery

Queues the delivery again at once with its attempt count reset. It keeps its webhook-id, so receivers can deduplicate.

Auth: an API key with webhooks:write (or full), or a session with role owner, admin.

Parameters

idstringpathrequired

Idempotency-Keystringheader

x-org-idstringheader

With a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.

referalli-modestringheader

test runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.

live | test

Code samples

cURL

curl -X POST "https://referalli.com/v1/webhook-deliveries/{id}/replay" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/webhook-deliveries/{id}/replay', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/webhook-deliveries/{id}/replay",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/webhook-deliveries/{id}/replay", nil)
	req.Header.Set("Idempotency-Key", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/webhook-deliveries/{id}/replay');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/webhook-deliveries/{id}/replay')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://referalli.com/v1/webhook-deliveries/{id}/replay"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .method("POST", BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "ok": true
}

Schema

okbooleanrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

401 Missing or invalid credentials. error.code is one of:

Example

{
  "error": {
    "code": "unauthorized",
    "message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
    "docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

403 Authenticated, but not allowed. error.code is one of:

Example

{
  "error": {
    "code": "forbidden",
    "message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
    "docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

404 No such resource. error.code is one of:

Example

{
  "error": {
    "code": "not_found",
    "message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
    "docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

409 The request conflicts with the current state. error.code is one of:

Example

{
  "error": {
    "code": "conflict",
    "message": "a unique value is taken, or the action would break a rule (the message says which)",
    "docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

422 The request cannot be processed as sent. error.code is one of:

Example

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "the `idempotency-key` was used for a different request",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

429 Rate limited. error.code is one of:

Example

{
  "error": {
    "code": "rate_limited",
    "message": "an endpoint limit or the per-key quota was exceeded",
    "docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

500 Unexpected server error. error.code is one of:

Example

{
  "error": {
    "code": "internal_error",
    "message": "retry with backoff",
    "requestId": "req_8f2c1d4e5a6b7c8d",
    "docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

default Any other error, in the same envelope.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "requestId": "string",
    "docs_url": "string"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

WEBHOOKclick.recorded

A tracked click was recorded

Fires for every click (tracked link redirects, ?via= landings, server-side clicks). High volume: subscribe only if you need click-level data.

POSTed to every active webhook endpoint subscribed to click.recorded (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A tracked click was recorded: the click.recorded delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a click.recorded event: Fires for every click (tracked link redirects, ?via= landings, server-side clicks). High volume: subscribe only if you need click-level data.

Show child parameters

clickIdstringrequired

programIdstringrequired

partnerIdstringrequired

linkIdstringrequired

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "clickId": "string",
    "programId": "string",
    "partnerId": "string",
    "linkId": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKreferral.created

A customer was attributed to a partner

A new referral: from POST /v1/referrals/associate, an auth-platform sign-up, a mobile install, a won deal or an agent attribution.

POSTed to every active webhook endpoint subscribed to referral.created (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A customer was attributed to a partner: the referral.created delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a referral.created event: A new referral: from POST /v1/referrals/associate, an auth-platform sign-up, a mobile install, a won deal or an agent attribution.

Show child parameters

referralIdstringrequired

programIdstringrequired

partnerIdstringrequired

partnerExternalRefstringrequired

The partner's id in your own system (its externalRef), or null.

customerRefstringrequired

Your id for the referred customer.

statusstringrequired

active | pending_review | paused | void

matchedViastringrequired

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "referralId": "string",
    "programId": "string",
    "partnerId": "string",
    "partnerExternalRef": "string",
    "customerRef": "string",
    "status": "active",
    "matchedVia": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKreferral.held

A referral was held for review

A risk or self-referral check put the referral in pending_review; reasons says why and caseId is the fraud case opened for it.

POSTed to every active webhook endpoint subscribed to referral.held (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A referral was held for review: the referral.held delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a referral.held event: A risk or self-referral check put the referral in pending_review; reasons says why and caseId is the fraud case opened for it.

Show child parameters

referralIdstringrequired

programIdstringrequired

partnerIdstringrequired

partnerExternalRefstringrequired

The partner's id in your own system (its externalRef), or null.

customerRefstringrequired

Your id for the referred customer.

statusstringrequired

active | pending_review | paused | void

reasonsstring[]required

caseIdstringrequired

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "referralId": "string",
    "programId": "string",
    "partnerId": "string",
    "partnerExternalRef": "string",
    "customerRef": "string",
    "status": "active",
    "reasons": [
      "string"
    ],
    "caseId": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKreferral.approved

A held referral was approved

Back to active: approved by the merchant, a fraud case dismissed (reason: "fraud_case_dismissed", with caseId), or a hold released by email verification (reason: "email_verified").

POSTed to every active webhook endpoint subscribed to referral.approved (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A held referral was approved: the referral.approved delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a referral.approved event: Back to active: approved by the merchant, a fraud case dismissed (reason: "fraud_case_dismissed", with caseId), or a hold released by email verification (reason: "email_verified").

Show child parameters

referralIdstringrequired

programIdstringrequired

partnerIdstringrequired

partnerExternalRefstringrequired

The partner's id in your own system (its externalRef), or null.

customerRefstringrequired

Your id for the referred customer.

statusstringrequired

active | pending_review | paused | void

reasonstring

caseIdstring

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "referralId": "string",
    "programId": "string",
    "partnerId": "string",
    "partnerExternalRef": "string",
    "customerRef": "string",
    "status": "active",
    "reason": "string",
    "caseId": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKreferral.voided

A referral was voided

It earns nothing more: voided by the merchant, a fraud case (reason fraud_case_voided or partner_banned, with caseId) or an identity provider (fraud_confirmed).

POSTed to every active webhook endpoint subscribed to referral.voided (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A referral was voided: the referral.voided delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a referral.voided event: It earns nothing more: voided by the merchant, a fraud case (reason fraud_case_voided or partner_banned, with caseId) or an identity provider (fraud_confirmed).

Show child parameters

referralIdstringrequired

programIdstringrequired

partnerIdstringrequired

partnerExternalRefstringrequired

The partner's id in your own system (its externalRef), or null.

customerRefstringrequired

Your id for the referred customer.

statusstringrequired

active | pending_review | paused | void

reasonstring

caseIdstring

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "referralId": "string",
    "programId": "string",
    "partnerId": "string",
    "partnerExternalRef": "string",
    "customerRef": "string",
    "status": "active",
    "reason": "string",
    "caseId": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKreferral.paused

A referral was paused

The merchant paused the referral: it earns no new commissions until resumed.

POSTed to every active webhook endpoint subscribed to referral.paused (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A referral was paused: the referral.paused delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a referral.paused event: The merchant paused the referral: it earns no new commissions until resumed.

Show child parameters

referralIdstringrequired

programIdstringrequired

partnerIdstringrequired

partnerExternalRefstringrequired

The partner's id in your own system (its externalRef), or null.

customerRefstringrequired

Your id for the referred customer.

statusstringrequired

active | pending_review | paused | void

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "referralId": "string",
    "programId": "string",
    "partnerId": "string",
    "partnerExternalRef": "string",
    "customerRef": "string",
    "status": "active"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKreferral.resumed

A paused referral was resumed

The referral is active again.

POSTed to every active webhook endpoint subscribed to referral.resumed (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A paused referral was resumed: the referral.resumed delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a referral.resumed event: The referral is active again.

Show child parameters

referralIdstringrequired

programIdstringrequired

partnerIdstringrequired

partnerExternalRefstringrequired

The partner's id in your own system (its externalRef), or null.

customerRefstringrequired

Your id for the referred customer.

statusstringrequired

active | pending_review | paused | void

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "referralId": "string",
    "programId": "string",
    "partnerId": "string",
    "partnerExternalRef": "string",
    "customerRef": "string",
    "status": "active"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKreferral.reassigned

A referral moved to another partner

The merchant reassigned the referral; the payload names the new partner, with the previous one in previousPartnerId and previousPartnerExternalRef.

POSTed to every active webhook endpoint subscribed to referral.reassigned (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A referral moved to another partner: the referral.reassigned delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a referral.reassigned event: The merchant reassigned the referral; the payload names the new partner, with the previous one in previousPartnerId and previousPartnerExternalRef.

Show child parameters

referralIdstringrequired

programIdstringrequired

partnerIdstringrequired

partnerExternalRefstringrequired

The partner's id in your own system (its externalRef), or null.

customerRefstringrequired

Your id for the referred customer.

statusstringrequired

active | pending_review | paused | void

previousPartnerIdstringrequired

previousPartnerExternalRefstringrequired

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "referralId": "string",
    "programId": "string",
    "partnerId": "string",
    "partnerExternalRef": "string",
    "customerRef": "string",
    "status": "active",
    "previousPartnerId": "string",
    "previousPartnerExternalRef": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKreferral.rejected

A self-referral was refused

A self-referral the program's selfReferralPolicy: "reject" refused, so no referral exists. A fraud.case_opened follows.

POSTed to every active webhook endpoint subscribed to referral.rejected (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A self-referral was refused: the referral.rejected delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a referral.rejected event: A self-referral the program's selfReferralPolicy: "reject" refused, so no referral exists. A fraud.case_opened follows.

Show child parameters

programIdstringrequired

partnerIdstringrequired

customerRefstringrequired

reasonstringrequired

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "programId": "string",
    "partnerId": "string",
    "customerRef": "string",
    "reason": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKcustomer.aliased

A customer's id changed

The app changed a user's id after their sign-up was filed (through an auth connection); their referrals now use toCustomerRef.

POSTed to every active webhook endpoint subscribed to customer.aliased (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A customer's id changed: the customer.aliased delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a customer.aliased event: The app changed a user's id after their sign-up was filed (through an auth connection); their referrals now use toCustomerRef.

Show child parameters

fromCustomerRefstringrequired

toCustomerRefstringrequired

referralIdsstring[]required

partnerIdstringrequired

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "fromCustomerRef": "string",
    "toCustomerRef": "string",
    "referralIds": [
      "string"
    ],
    "partnerId": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKcommission.earned

A commission line was earned

A payment (or a signup, trial or product-event bounty) earned a partner a commission line. Payment fields are null for bounties.

POSTed to every active webhook endpoint subscribed to commission.earned (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A commission line was earned: the commission.earned delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a commission.earned event: A payment (or a signup, trial or product-event bounty) earned a partner a commission line. Payment fields are null for bounties.

Show child parameters

commissionIdstringrequired

partnerIdstringrequired

programIdstringrequired

amountMinorintegerrequired

Integer minor units (cents).

currencystringrequired

Lowercase ISO 4217 code.

referralIdstringrequired

customerRefstringrequired

billingEventIdstringrequired

providerEventIdstringrequired

The billing provider's own event id.

invoiceRefstringrequired

customerExternalRefstringrequired

Your own id for the customer when known (an auth-connection user id), or null.

partnerExternalRefstringrequired

levelintegerrequired

0 for the direct partner, 1 to 5 for sub-affiliate levels.

memostringrequired

basisMinorintegerrequired

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "commissionId": "string",
    "partnerId": "string",
    "programId": "string",
    "amountMinor": 0,
    "currency": "string",
    "referralId": "string",
    "customerRef": "string",
    "billingEventId": "string",
    "providerEventId": "string",
    "invoiceRef": "string",
    "customerExternalRef": "string",
    "partnerExternalRef": "string",
    "level": 0,
    "memo": "string",
    "basisMinor": 0
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKcommission.reversed

A commission line was reversed

A refund or dispute clawed back an earned line. commissionId and relatedCommissionId are the original line, reversalId the new reversed event; amountMinor is negative.

POSTed to every active webhook endpoint subscribed to commission.reversed (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A commission line was reversed: the commission.reversed delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a commission.reversed event: A refund or dispute clawed back an earned line. commissionId and relatedCommissionId are the original line, reversalId the new reversed event; amountMinor is negative.

Show child parameters

commissionIdstringrequired

relatedCommissionIdstringrequired

reversalIdstringrequired

partnerIdstringrequired

programIdstringrequired

amountMinorintegerrequired

Negative: the amount taken back.

currencystringrequired

Lowercase ISO 4217 code.

referralIdstringrequired

customerRefstringrequired

billingEventIdstringrequired

providerEventIdstringrequired

The billing provider's own event id.

invoiceRefstringrequired

customerExternalRefstringrequired

Your own id for the customer when known (an auth-connection user id), or null.

partnerExternalRefstringrequired

levelintegerrequired

0 for the direct partner, 1 to 5 for sub-affiliate levels.

memostringrequired

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "commissionId": "string",
    "relatedCommissionId": "string",
    "reversalId": "string",
    "partnerId": "string",
    "programId": "string",
    "amountMinor": 0,
    "currency": "string",
    "referralId": "string",
    "customerRef": "string",
    "billingEventId": "string",
    "providerEventId": "string",
    "invoiceRef": "string",
    "customerExternalRef": "string",
    "partnerExternalRef": "string",
    "level": 0,
    "memo": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKcommission.settled

A commission line was settled by the merchant

The merchant paid the line itself (store_credit, or merchant_credit for programs that settle as they earn), outside payout runs.

POSTed to every active webhook endpoint subscribed to commission.settled (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A commission line was settled by the merchant: the commission.settled delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a commission.settled event: The merchant paid the line itself (store_credit, or merchant_credit for programs that settle as they earn), outside payout runs.

Show child parameters

commissionIdstringrequired

partnerIdstringrequired

programIdstringrequired

referralIdstringrequired

amountMinorintegerrequired

Integer minor units (cents).

currencystringrequired

Lowercase ISO 4217 code.

methodstringrequired

store_credit | merchant_credit

referencestringrequired

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "commissionId": "string",
    "partnerId": "string",
    "programId": "string",
    "referralId": "string",
    "amountMinor": 0,
    "currency": "string",
    "method": "store_credit",
    "reference": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKpartner.applied

A partner applied to a program

An application waiting for approval. enrollmentId is absent for applications from the public program page.

POSTed to every active webhook endpoint subscribed to partner.applied (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A partner applied to a program: the partner.applied delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a partner.applied event: An application waiting for approval. enrollmentId is absent for applications from the public program page.

Show child parameters

programIdstringrequired

partnerIdstringrequired

enrollmentIdstring

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "programId": "string",
    "partnerId": "string",
    "enrollmentId": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKpartner.enrolled

A partner was enrolled

The merchant (or an import) enrolled the partner in a program, approved at once.

POSTed to every active webhook endpoint subscribed to partner.enrolled (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A partner was enrolled: the partner.enrolled delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a partner.enrolled event: The merchant (or an import) enrolled the partner in a program, approved at once.

Show child parameters

programIdstringrequired

partnerIdstringrequired

enrollmentIdstringrequired

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "programId": "string",
    "partnerId": "string",
    "enrollmentId": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKpartner.approved

A partner was approved

An application was approved, or a partner joined a program that approves at once. enrollmentId is present when approved from an application.

POSTed to every active webhook endpoint subscribed to partner.approved (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A partner was approved: the partner.approved delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a partner.approved event: An application was approved, or a partner joined a program that approves at once. enrollmentId is present when approved from an application.

Show child parameters

programIdstringrequired

partnerIdstringrequired

enrollmentIdstring

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "programId": "string",
    "partnerId": "string",
    "enrollmentId": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKpartner.level_up

A partner reached a new level

Partner leveling promoted the partner; referrals is the count that qualified them.

POSTed to every active webhook endpoint subscribed to partner.level_up (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A partner reached a new level: the partner.level_up delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a partner.level_up event: Partner leveling promoted the partner; referrals is the count that qualified them.

Show child parameters

programIdstringrequired

partnerIdstringrequired

levelstringrequired

referralsintegerrequired

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "programId": "string",
    "partnerId": "string",
    "level": "string",
    "referrals": 0
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKpayout.scheduled

A payout was created in a run

A payout run included the partner; nothing has been paid yet.

POSTed to every active webhook endpoint subscribed to payout.scheduled (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A payout was created in a run: the payout.scheduled delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a payout.scheduled event: A payout run included the partner; nothing has been paid yet.

Show child parameters

payoutIdstringrequired

partnerIdstringrequired

amountMinorintegerrequired

Integer minor units (cents).

currencystringrequired

Lowercase ISO 4217 code.

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "payoutId": "string",
    "partnerId": "string",
    "amountMinor": 0,
    "currency": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKpayout.submitted

A payout was submitted to the provider

The payout provider accepted the payout and settles it asynchronously; payout.sent or payout.failed follows.

POSTed to every active webhook endpoint subscribed to payout.submitted (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A payout was submitted to the provider: the payout.submitted delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a payout.submitted event: The payout provider accepted the payout and settles it asynchronously; payout.sent or payout.failed follows.

Show child parameters

payoutIdstringrequired

partnerIdstringrequired

amountMinorintegerrequired

Integer minor units (cents).

currencystringrequired

Lowercase ISO 4217 code.

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "payoutId": "string",
    "partnerId": "string",
    "amountMinor": 0,
    "currency": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKpayout.sent

A payout was paid

The money left: the provider confirmed the payout (at once, or later through its settlement webhook).

POSTed to every active webhook endpoint subscribed to payout.sent (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A payout was paid: the payout.sent delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a payout.sent event: The money left: the provider confirmed the payout (at once, or later through its settlement webhook).

Show child parameters

payoutIdstringrequired

partnerIdstringrequired

amountMinorintegerrequired

Integer minor units (cents).

currencystringrequired

Lowercase ISO 4217 code.

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "payoutId": "string",
    "partnerId": "string",
    "amountMinor": 0,
    "currency": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKpayout.failed

A payout failed

The provider refused or failed the payout; reason is its message. The lines go back to the partner's approved balance.

POSTed to every active webhook endpoint subscribed to payout.failed (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A payout failed: the payout.failed delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a payout.failed event: The provider refused or failed the payout; reason is its message. The lines go back to the partner's approved balance.

Show child parameters

payoutIdstringrequired

partnerIdstringrequired

reasonstringrequired

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "payoutId": "string",
    "partnerId": "string",
    "reason": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKpayout.cancelled

A payout was cancelled

One per payout when an unexecuted payout run is cancelled.

POSTed to every active webhook endpoint subscribed to payout.cancelled (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A payout was cancelled: the payout.cancelled delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a payout.cancelled event: One per payout when an unexecuted payout run is cancelled.

Show child parameters

payoutIdstringrequired

partnerIdstringrequired

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "payoutId": "string",
    "partnerId": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKtax.form_delivered

A tax form was delivered to a partner

A filed 1099-NEC was accepted and delivered; emailed says whether the filing provider also emailed it.

POSTed to every active webhook endpoint subscribed to tax.form_delivered (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A tax form was delivered to a partner: the tax.form_delivered delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a tax.form_delivered event: A filed 1099-NEC was accepted and delivered; emailed says whether the filing provider also emailed it.

Show child parameters

documentIdstringrequired

partnerIdstringrequired

taxYearintegerrequired

formstringrequired

correctedbooleanrequired

emailedbooleanrequired

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "documentId": "string",
    "partnerId": "string",
    "taxYear": 0,
    "form": "string",
    "corrected": true,
    "emailed": true
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKreferee_reward.earned

A referred customer earned their reward

The friend's side of a double-sided program: the referred customer's reward was issued.

POSTed to every active webhook endpoint subscribed to referee_reward.earned (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A referred customer earned their reward: the referee_reward.earned delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a referee_reward.earned event: The friend's side of a double-sided program: the referred customer's reward was issued.

Show child parameters

rewardIdstringrequired

referralIdstringrequired

programIdstringrequired

customerRefstringrequired

customerExternalRefstringrequired

kindstringrequired

store_credit | coupon | gift_card

amountMinorintegerrequired

Integer minor units (cents).

currencystringrequired

Lowercase ISO 4217 code.

codestringrequired

billingEventIdstringrequired

commissionIdstringrequired

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "rewardId": "string",
    "referralId": "string",
    "programId": "string",
    "customerRef": "string",
    "customerExternalRef": "string",
    "kind": "store_credit",
    "amountMinor": 0,
    "currency": "string",
    "code": "string",
    "billingEventId": "string",
    "commissionId": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKcredit.redeemed

A referee reward was redeemed

From POST /v1/rewards/{id}/redeem or POST /v1/rewards/redeem-by-code. amountMinor is what this redemption used (capped at the balance); a repeated externalId does not fire again.

POSTed to every active webhook endpoint subscribed to credit.redeemed (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A referee reward was redeemed: the credit.redeemed delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a credit.redeemed event: From POST /v1/rewards/{id}/redeem or POST /v1/rewards/redeem-by-code. amountMinor is what this redemption used (capped at the balance); a repeated externalId does not fire again.

Show child parameters

grantIdstringrequired

rewardIdstringrequired

amountMinorintegerrequired

Integer minor units (cents).

remainingMinorintegerrequired

What is left on the grant afterwards.

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "grantId": "string",
    "rewardId": "string",
    "amountMinor": 0,
    "remainingMinor": 0
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKbilling_event.recorded

A billing event was recorded

Fires once per newly recorded billing event from any connection, never for duplicates.

POSTed to every active webhook endpoint subscribed to billing_event.recorded (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A billing event was recorded: the billing_event.recorded delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a billing_event.recorded event: Fires once per newly recorded billing event from any connection, never for duplicates.

Show child parameters

billingEventIdstringrequired

typestringrequired

customerRefstringrequired

currencystringrequired

Lowercase ISO 4217 code.

amountMinorintegerrequired

Integer minor units (cents).

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "billingEventId": "string",
    "type": "string",
    "customerRef": "string",
    "currency": "string",
    "amountMinor": 0
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKroi.payback_reached

A credit grant paid back

Once per credit grant, the first time its recipient's profit after it covered its cost. A later refund that un-pays it doesn't fire it again.

POSTed to every active webhook endpoint subscribed to roi.payback_reached (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A credit grant paid back: the roi.payback_reached delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a roi.payback_reached event: Once per credit grant, the first time its recipient's profit after it covered its cost. A later refund that un-pays it doesn't fire it again.

Show child parameters

grantIdstringrequired

paybackDaysintegerrequired

Whole days from the grant until it paid back.

netMinorintegerrequired

Profit after minus cost, when it paid back.

currencystringrequired

Lowercase ISO 4217 code.

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "grantId": "string",
    "paybackDays": 0,
    "netMinor": 0,
    "currency": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKroi.pattern_detected

A value pattern changed

A daily summary, at most once per pattern per day, only when the set of matching subjects changed and count is above zero. Read the full list from GET /v1/roi/patterns/{pattern}.

POSTed to every active webhook endpoint subscribed to roi.pattern_detected (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A value pattern changed: the roi.pattern_detected delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a roi.pattern_detected event: A daily summary, at most once per pattern per day, only when the set of matching subjects changed and count is above zero. Read the full list from GET /v1/roi/patterns/{pattern}.

Show child parameters

patternstringrequired

credit_only | churn_at_exhaustion | bonus_collector | negative_partner

countintegerrequired

Subjects matching today.

newCountintegerrequired

Of those, how many were not in the pattern's last report.

samplestring[]required

Up to 10 ids: credit grant ids for the first two patterns, partner ids for the others.

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "pattern": "credit_only",
    "count": 0,
    "newCount": 0,
    "sample": [
      "string"
    ]
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKfraud.case_opened

A fraud case was opened

A case is waiting in the queue. kind is self_referral, quality, ring, identity_risk or value_pattern; the other fields depend on it (partnerId, referralId, ring members, identity-risk reasons, value pattern). A self-referral rejected by policy has referralId: null and rejected: true.

POSTed to every active webhook endpoint subscribed to fraud.case_opened (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A fraud case was opened: the fraud.case_opened delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a fraud.case_opened event: A case is waiting in the queue. kind is self_referral, quality, ring, identity_risk or value_pattern; the other fields depend on it (partnerId, referralId, ring members, identity-risk reasons, value pattern). A self-referral rejected by policy has referralId: null and rejected: true.

Show child parameters

caseIdstringrequired

kindstringrequired

self_referral | quality | ring | identity_risk | value_pattern

partnerIdstring

referralIdstring

membersstring[]

reasonsstring[]

patternstring

rejectedboolean

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "caseId": "string",
    "kind": "self_referral",
    "partnerId": "string",
    "referralId": "string",
    "members": [
      "string"
    ],
    "reasons": [
      "string"
    ],
    "pattern": "string",
    "rejected": true
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKdeal.submitted

A partner registered a deal

A B2B deal waiting for the merchant to approve.

POSTed to every active webhook endpoint subscribed to deal.submitted (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A partner registered a deal: the deal.submitted delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a deal.submitted event: A B2B deal waiting for the merchant to approve.

Show child parameters

dealIdstringrequired

partnerIdstringrequired

companystringrequired

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "dealId": "string",
    "partnerId": "string",
    "company": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKdispute.resolved

A partner dispute was resolved

The merchant resolved a partner's dispute with the resolution note.

POSTed to every active webhook endpoint subscribed to dispute.resolved (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A partner dispute was resolved: the dispute.resolved delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a dispute.resolved event: The merchant resolved a partner's dispute with the resolution note.

Show child parameters

disputeIdstringrequired

resolutionstringrequired

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "disputeId": "string",
    "resolution": "string"
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKprivacy.request_completed

A data-subject request finished

An access or erasure request opened with POST /v1/privacy/requests completed or failed; found is present when completed.

POSTed to every active webhook endpoint subscribed to privacy.request_completed (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A data-subject request finished: the privacy.request_completed delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a privacy.request_completed event: An access or erasure request opened with POST /v1/privacy/requests completed or failed; found is present when completed.

Show child parameters

requestIdstringrequired

typestringrequired

access | erasure

statusstringrequired

completed | failed

foundboolean

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "requestId": "string",
    "type": "access",
    "status": "completed",
    "found": true
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

WEBHOOKwebhook_endpoint.disabled

A failing webhook endpoint was disabled

Sent to your other active endpoints when one is disabled after every delivery failed for 5 days.

POSTed to every active webhook endpoint subscribed to webhook_endpoint.disabled (or *), signed the Standard Webhooks way. Answer any 2xx within 15 seconds; anything else is retried with backoff for 3 days.

Parameters

webhook-idstringheaderrequired

The delivery id; the same on every retry and replay. Deduplicate on it.

webhook-timestampintegerheaderrequired

When this attempt was signed, in unix seconds. Reject it when more than 5 minutes from your clock.

webhook-signaturestringheaderrequired

v1, plus the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded secret after whsec_. During a rotation, two signatures separated by a space.

x-referalli-topicstringheaderrequired

The event topic, as in the body. The legacy header names from before the rename are also sent, with identical values, for existing integrations.

Payload application/json

A failing webhook endpoint was disabled: the webhook_endpoint.disabled delivery body.

idstringrequired

The event id (evt_…); the same event delivered to several endpoints has the same id.

topicstringrequired

orgIdstringrequired

livemodebooleanrequired

false for events from test mode.

createdAtstringrequired

dataobjectrequired

data of a webhook_endpoint.disabled event: Sent to your other active endpoints when one is disabled after every delivery failed for 5 days.

Show child parameters

endpointIdstringrequired

urlstringrequired

reasonstringrequired

lastStatusCodeintegerrequired

daysintegerrequired

{
  "id": "string",
  "topic": "string",
  "orgId": "string",
  "livemode": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "data": {
    "endpointId": "string",
    "url": "string",
    "reason": "string",
    "lastStatusCode": 0,
    "days": 0
  }
}

Responses

200 Received. Any 2xx acknowledges the delivery.

Updated Oct 23, 2026

Was this page helpful?