Webhook Endpoints
REST API reference for webhook endpoints
This reference is generated from the Invitebase OpenAPI contract.
Customer-registered URLs for outbound events.
List webhook endpoints
Authentication
Authorization: Bearer <secret key>.
Parameters
| Name | In | Required | Schema | Description |
|---|---|---|---|---|
limit | query | No | {"type":"integer","minimum":1,"maximum":100,"default":25} | |
starting_after | query | No | {"type":"string"} | A cursor (object id) for pagination; returns the page after this object. |
Responses
200
A list of webhook endpoints.
application/json schema:
{
"allOf": [
{
"$ref": "#/components/schemas/ListResponse"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookEndpoint"
}
}
}
}
]
}400
The request was malformed or invalid.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}401
Missing or invalid API key.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}403
The API key is valid but is not permitted to call this endpoint.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}429
Too many requests.
Response headers:
{
"Retry-After": {
"description": "Seconds until the caller may retry.",
"schema": {
"type": "integer",
"minimum": 1
}
}
}application/json schema:
{
"$ref": "#/components/schemas/Error"
}Create a webhook endpoint
Authentication
Authorization: Bearer <secret key>.
Parameters
| Name | In | Required | Schema | Description |
|---|---|---|---|---|
Idempotency-Key | header | No | {"type":"string"} | A unique key for one logical mutation. The same key and request replay the original result for 24 hours; using the key with a different request returns 409. |
Request body
Required.
application/json schema:
{
"$ref": "#/components/schemas/WebhookEndpointCreate"
}Responses
201
Webhook endpoint created. The signing secret is returned once.
application/json schema:
{
"$ref": "#/components/schemas/WebhookEndpoint"
}400
The request was malformed or invalid.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}401
Missing or invalid API key.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}403
The API key is valid but is not permitted to call this endpoint.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}409
The request conflicts with the resource's current state.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}429
Too many requests.
Response headers:
{
"Retry-After": {
"description": "Seconds until the caller may retry.",
"schema": {
"type": "integer",
"minimum": 1
}
}
}application/json schema:
{
"$ref": "#/components/schemas/Error"
}Schemas
Schema references below resolve against these definitions. Required fields, enums, bounds, and composed types are preserved from the contract.
The ListResponse object
| Field | Type | Required | Description |
|---|---|---|---|
object | string | Yes | |
has_more | boolean | Yes | |
data | array | Yes |
Full schema:
{
"type": "object",
"required": [
"object",
"data",
"has_more"
],
"properties": {
"object": {
"type": "string",
"const": "list"
},
"has_more": {
"type": "boolean"
},
"data": {
"type": "array",
"items": {}
}
}
}The WebhookEndpoint object
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | |
enabled_events | array | Yes | Which events to deliver. reward.pending is how app-grant rewards are delivered — the signed webhook tells the customer's backend what to grant. |
id | string | Yes | |
object | string | Yes | |
signing_secret | string | No | Returned only on creation. Used to verify the Invitebase-Signature header. |
mode | Mode | No | Whether the object exists in test or live mode (determined by the API key). |
created_at | string | No |
Full schema:
{
"allOf": [
{
"$ref": "#/components/schemas/WebhookEndpointCreate"
},
{
"type": "object",
"required": [
"id",
"object"
],
"properties": {
"id": {
"type": "string",
"example": "whe_123"
},
"object": {
"type": "string",
"const": "webhook_endpoint"
},
"signing_secret": {
"type": "string",
"description": "Returned only on creation. Used to verify the Invitebase-Signature header."
},
"mode": {
"$ref": "#/components/schemas/Mode"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
]
}Event types
| Event type | Fires when |
|---|---|
referral.credited | A signup is attributed to a referrer (linked, not yet validated). |
referral.validated | A referral passes all qualification gates and the AI fraud check. |
referral.rejected | A referral is rejected by the AI fraud check, or reversed after validation. |
referral.expired | The qualification window passed before the gates were met. |
reward.pending | A reward is created off a validated referral and is ready to act on — for app grants, your cue to grant it in your backend and confirm it. |
reward.held_for_review | A reward is held back from fulfillment until it is approved. |
reward.fulfilled | A reward completes fulfillment (app grant confirmed or payout completed). |
reward.failed | A payout fails after retries (money rewards only). |
payout.available | A cash or gift-card payout becomes claimable by a referrer. |
balance.low | The prefunded balance crosses its low-balance threshold. |
Money-rail rewards fulfill through the payout provider whether or not deliveries succeed; app-grant rewards stay pending until your backend confirms them, so treat reward.pending as the work signal, not a courtesy. See the full catalog with payload shapes in Webhooks.
The WebhookEndpointCreate object
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | |
enabled_events | array | Yes | Which events to deliver. reward.pending is how app-grant rewards are delivered — the signed webhook tells the customer's backend what to grant. |
Full schema:
{
"type": "object",
"required": [
"url",
"enabled_events"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"enabled_events": {
"type": "array",
"items": {
"type": "string",
"enum": [
"referral.credited",
"referral.in_progress",
"referral.validated",
"referral.rejected",
"referral.expired",
"reward.pending",
"reward.held_for_review",
"reward.fulfilled",
"reward.failed",
"payout.available",
"balance.low"
]
},
"description": "Which events to deliver. `reward.pending` is how app-grant rewards are delivered — the signed webhook tells the customer's backend what to grant.\n"
}
}
}The Mode object
Whether the object exists in test or live mode (determined by the API key).
Full schema:
{
"type": "string",
"enum": [
"test",
"live"
],
"description": "Whether the object exists in test or live mode (determined by the API key)."
}The Error object
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes |
Full schema:
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"doc_url"
],
"properties": {
"type": {
"type": "string",
"enum": [
"invalid_request_error",
"authentication_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}