Webhook endpoints
Registered URLs for outbound signed events
Webhook endpoints are the URLs Invitebase delivers outbound events to — including the reward.pending events that deliver app-grant rewards to your backend. Every delivery is HMAC-signed with the endpoint's signing secret in the Invitebase-Signature header; verify it before acting. See Webhooks for signature verification and retry semantics.
The WebhookEndpoint object
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier (a UUID). |
object | string | Always webhook_endpoint. |
url | string | The HTTPS URL deliveries are sent to. |
enabled_events | array | Which event types to deliver (below). |
signing_secret | string | Returned only on creation. Used to verify the Invitebase-Signature header. |
mode | string | test or live. Endpoints are registered per mode. |
livemode | boolean | Whether the endpoint exists in live mode. |
created_at | string (date-time) | Creation 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 fraud checks. |
referral.rejected | A referral is rejected by the fraud rules, 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.
List webhook endpoints
Returns your registered endpoints in the key's mode. The signing_secret is not included — it is shown only once, at creation.
curl https://api.invitebase.com/v1/webhook_endpoints \
-H "Authorization: Bearer $INVITEBASE_SECRET_KEY"Response — 200 OK:
{
"object": "list",
"has_more": false,
"data": [
{
"id": "3f8b2d61-7a4c-4e95-b1d0-2c6e9a5f8d13",
"object": "webhook_endpoint",
"url": "https://api.example.com/invitebase/webhooks",
"enabled_events": ["referral.validated", "reward.pending", "reward.failed"],
"mode": "test",
"livemode": false,
"created_at": "2026-07-01T09:30:00.000Z"
}
]
}Create a webhook endpoint
Registers a URL and the event types it should receive. The response includes the signing_secret — store it now; it is returned only once.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
url | body | string | Yes | The HTTPS URL to deliver events to. |
enabled_events | body | array of strings | Yes | One or more event types. |
curl https://api.invitebase.com/v1/webhook_endpoints \
-H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.example.com/invitebase/webhooks",
"enabled_events": ["referral.validated", "reward.pending", "reward.failed"]
}'Response — 201 Created:
{
"id": "3f8b2d61-7a4c-4e95-b1d0-2c6e9a5f8d13",
"object": "webhook_endpoint",
"url": "https://api.example.com/invitebase/webhooks",
"enabled_events": ["referral.validated", "reward.pending", "reward.failed"],
"signing_secret": "whsec_Zk9mQ2xhdWRlRXhhbXBsZVNlY3JldE5vdFJlYWw0Mg",
"mode": "test",
"livemode": false,
"created_at": "2026-07-09T10:20:00.000Z"
}Returns 400 if the URL is not valid public HTTPS or an event type is unknown, and 409 (code webhook_endpoint_exists) if the URL is already registered for this app and mode. See Errors.
Deliveries are at-least-once with exponential-backoff retries. You can send test deliveries and redeliver past events from Developer tools in the dashboard.