> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrip.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Start with the plan page, https://docs.scrip.dev/agents.md. It covers connecting, configuring, integrating, verifying, and operating a Scrip program.
> Events are asynchronous. `POST /v1/events` returns 202 when the event is accepted. Rules run afterward, so wait for the `event.completed` webhook or poll `GET /v1/events/{id}` before you read balances.
> Send the participant's `external_id` with an event. The first event for a new `external_id` enrolls the participant, so do not create participants first.
> The hosted MCP server is https://mcp.scrip.dev/mcp. It uses OAuth and is read-only. Make changes through the REST API or the dashboard.
> Add `.md` to any docs URL to get the page as Markdown. Request and response schemas are in https://docs.scrip.dev/openapi.json.
# List webhook event types
> List every webhook event type with its category and a sample `data` object.
A catalog list does not accept created_after or created_before.
Returns every webhook event type. Each row carries the `type`, its `category`, a one-sentence `description`, and a `sample_payload`. The response uses the standard list shape, with `data` and `pagination`.
Use this call to find the event types you can subscribe an endpoint to, and to see the payload shape for each one before you write a handler. Pass any type from the list as the `event_type` when you send a test webhook.
For the meaning of each event and how to read a payload, see [Webhook event types](/guides/webhooks#webhook-event-types) in the Webhooks guide.
## OpenAPI
````yaml GET /v1/webhook-event-types
openapi: 3.1.0
info:
contact:
email: support@scrip.dev
name: Scrip Support
description: >-
Scrip is the operating system for rewards programs. Use this REST API to
define earn and redemption rules, issue and redeem assets, and track every
movement in a double-entry ledger. Full guides and reference:
https://docs.scrip.dev
Core concepts:
- **Programs**: Containers for incentive logic (e.g., "Q1 Sales Bonus",
"Customer Loyalty")
- **Assets**: The currency or points being tracked (e.g., "Bonus Points",
"Cash Rewards")
- **Participants**: Users who earn and spend assets (identified by
external_id)
- **Groups**: Collections of participants for team-based incentives
- **Rules**: Automated reward logic triggered by events
- **Events**: Actions that trigger rule evaluation (e.g., "purchase",
"referral")
Response formats:
- **Collection endpoints** return: {"data": [...], "pagination":
{"has_more": true, "next_cursor": "..."}}
- **Single-resource endpoints** return the resource directly
- **Errors** return: {"type": "...", "code": "...", "message": "...",
"request_id": "...", "doc_url": "..."}, plus `param`, `fields` and `details`
when they apply. Branch on `code`; quote `request_id` to support.
Bucket casing: balance responses use lowercase object keys (`available`,
`held`, `deferred`). A bucket you send or filter by is an UPPER_SNAKE value
(`AVAILABLE`, `HELD`, `DEFERRED`).
Authentication: send your API key as `Authorization: Bearer ` on every
request.
Request bodies: send `Content-Type: application/json` on every request that
has a body, or the API returns 415 with code `unsupported_media_type`.
Rate limits: build to 10 requests per second. Each API instance enforces its
own ceiling and reports it in `X-RateLimit-Limit`, so the value is the
ceiling of the instance that served your request. When you go over, the API
returns 429 with a `Retry-After` header that gives the seconds to wait.
Retries: every operation carries `x-scrip-idempotency`. `replay` means Scrip
stores the first outcome under your `Idempotency-Key` for 24 hours and
returns it again. `conflict_safe` means the route keeps its own permanent
record, so the same key with the same fields returns the first result.
`natural_key` means the request names its own identity, such as a
participant's `external_id` or an event's `idempotency_key`. `none` means
the route needs no key.
Webhooks: Scrip also calls your endpoints. The `webhooks` section describes
every event type, with the payload Scrip sends and a sample.
license:
name: Proprietary
termsOfService: https://scrip.dev/terms
title: Scrip API
version: '1.0'
servers:
- url: https://api.scrip.dev
security: []
tags:
- description: >-
Manage incentive programs. Programs are the top-level container for all
incentive logic.
name: Programs
- description: >-
Manage asset types (currencies, points). Assets define what participants
can earn and spend.
name: Assets
- description: >-
Manage participants and their balances. Participants are identified by
external_id from your system.
name: Participants
- description: Manage participant groups for team-based incentives.
name: Groups
- description: >-
Manage automated reward rules. Rules define conditions and actions
triggered by events.
name: Rules
- description: Ingest events that trigger rule evaluation and reward distribution.
name: Events
- description: Transfer assets between participants.
name: Transfers
- description: Access ledger summaries and program activity reports.
name: Reporting
- description: >-
Redeem participant balances for rewards. Supports raw amount redemptions
and catalog item redemptions.
name: Redemptions
- description: >-
Manage the reward catalog. Create and manage redeemable items with
inventory tracking.
name: Rewards
- description: >-
Schedule and manage automated event dispatching. Automations generate
events on cron schedules, at specific times, or by evaluating participant
state.
name: Automations
- description: >-
Manage tier types and levels within programs. Tiers define status
hierarchies that participants progress through based on qualification
rules.
name: Tiers
- description: Inspect double-entry ledger records for auditing and reconciliation.
name: Journal Entries
- description: >-
Manage webhook endpoints and delivery logs. Webhooks notify your
application of real-time events via HTTP POST with HMAC-SHA256 signatures.
name: Webhooks
- description: >-
Inspect the gift-card provider accounts that fulfill redemptions, and the
products each one offers.
name: Fulfillment Accounts
- description: >-
Connect a program to a fulfillment account so its catalog backs rewards,
and choose which products the program offers.
name: Reward Sources
- description: >-
Group a program's rules into ordered sets, and reorder the sets and the
rules inside them.
name: Rule Sets
- description: >-
Events Scrip sends to your webhook endpoints. Each key under `webhooks` is
an event type, and its request body is the delivery.
name: Webhook events
paths:
/v1/webhook-event-types:
get:
tags:
- Webhooks
summary: List webhook event types
description: >-
List every webhook event type with its category and a sample `data`
object.
A catalog list does not accept created_after or created_before.
operationId: listWebhookEventTypes
responses:
'200':
content:
application/json:
examples:
default:
value:
data:
- category: movement
description: 'A balance increased: a credit, a reward, or a settle.'
type: balance.credited
pagination:
has_more: true
next_cursor: YWJjMTIz
schema:
$ref: '#/components/schemas/WebhookEventTypeListResponse'
description: Every webhook event type
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalError'
security:
- BearerAuth: []
components:
schemas:
WebhookEventTypeListResponse:
description: >-
One page of webhook event types, with the pagination details for the
next page.
properties:
data:
description: The webhook event types on this page.
items:
$ref: '#/components/schemas/WebhookEventTypeResponse'
type: array
pagination:
allOf:
- $ref: '#/components/schemas/PaginationResponse'
description: Whether another page follows, and the cursor that fetches it.
type: object
WebhookEventTypeResponse:
description: >-
One webhook event type, with a sentence on when it fires and a sample
payload.
properties:
category:
description: >-
`movement` events announce one journal entry each. `lifecycle`
events announce a resource changing state.
enum:
- movement
- lifecycle
examples:
- movement
type: string
description:
description: One sentence saying when the event fires.
examples:
- 'A balance increased: a credit, a reward, or a settle.'
type: string
sample_payload:
description: >-
A sample of the envelope's `data` object for this type, filled with
sample ids.
type: object
type:
description: >-
The event type, as it appears in an envelope's `type` and in
`enabled_events`.
examples:
- balance.credited
type: string
type: object
PaginationResponse:
description: >-
Cursor details for a list. `has_more` says whether another page exists,
and `next_cursor` is the value to send to get it.
properties:
has_more:
description: Whether more results are available beyond this page
examples:
- true
type: boolean
next_cursor:
description: Cursor to fetch the next page. Null on the last page
examples:
- YWJjMTIz
type:
- string
- 'null'
required:
- has_more
- next_cursor
type: object
ErrUnauthorizedResponse:
description: 'The error body for a 401 response: the API key is missing or not valid.'
properties:
code:
description: >-
The specific reason for the error. Branch on this value, not on
message
examples:
- invalid_api_key
type: string
details:
additionalProperties: true
description: Extra context for this code, documented per code on the errors page
type: object
doc_url:
description: A link to this code on the errors page
examples:
- https://docs.scrip.dev/errors#invalid_api_key
type: string
fields:
description: Every failing field on a validation_error, reported in one pass
items:
$ref: '#/components/schemas/ErrorFieldDetail'
type: array
message:
description: What happened and what to do next, in one or two sentences
examples:
- >-
The API key in the Authorization header is unknown, revoked or
needs rotation.
type: string
param:
description: The one request field at fault, when there is one
type: string
request_id:
description: >-
The id of this request, the same req_ value as the X-Request-ID
response header. Quote it when you contact support
examples:
- req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: string
type:
description: The error family. It is one value per HTTP status
examples:
- authentication
type: string
type: object
ErrForbiddenResponse:
description: 'The error body for a 403 response: the caller is not allowed to do this.'
properties:
code:
description: >-
The specific reason for the error. Branch on this value, not on
message
examples:
- insufficient_permissions
type: string
details:
additionalProperties: true
description: Extra context for this code, documented per code on the errors page
type: object
doc_url:
description: A link to this code on the errors page
examples:
- https://docs.scrip.dev/errors#insufficient_permissions
type: string
fields:
description: Every failing field on a validation_error, reported in one pass
items:
$ref: '#/components/schemas/ErrorFieldDetail'
type: array
message:
description: What happened and what to do next, in one or two sentences
examples:
- >-
Your role or key does not include the capability this endpoint
needs.
type: string
param:
description: The one request field at fault, when there is one
type: string
request_id:
description: >-
The id of this request, the same req_ value as the X-Request-ID
response header. Quote it when you contact support
examples:
- req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: string
type:
description: The error family. It is one value per HTTP status
examples:
- permission
type: string
type: object
ErrTooManyRequestsResponse:
additionalProperties: false
description: >-
The error body for a 429 response: you sent more requests than the rate
limit allows.
properties:
code:
description: >-
The specific reason for the error. Branch on this value, not on
message
examples:
- rate_limit_exceeded
type: string
details:
additionalProperties: true
description: Extra context for this code, documented per code on the errors page
type: object
doc_url:
description: A link to this code on the errors page
examples:
- https://docs.scrip.dev/errors#rate_limit_exceeded
type: string
fields:
description: Every failing field on a validation_error, reported in one pass
items:
$ref: '#/components/schemas/ErrorFieldDetail'
type: array
message:
description: What happened and what to do next, in one or two sentences
examples:
- Rate limit exceeded. Wait for the Retry-After delay, then retry.
type: string
param:
description: The one request field at fault, when there is one
type: string
request_id:
description: >-
The id of this request, the same req_ value as the X-Request-ID
response header. Quote it when you contact support
examples:
- req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: string
type:
description: The error family. It is one value per HTTP status
examples:
- rate_limited
type: string
type: object
ErrInternalResponse:
description: >-
The error body for a 500 response: something failed on Scrip's side.
Quote the `request_id` when you contact support.
properties:
code:
description: >-
The specific reason for the error. Branch on this value, not on
message
examples:
- internal_error
type: string
doc_url:
description: A link to this code on the errors page
examples:
- https://docs.scrip.dev/errors#internal_error
type: string
message:
description: What happened and what to do next, in one or two sentences
examples:
- >-
An internal error occurred. Retry the request; if it keeps
failing, contact support with the request_id.
type: string
request_id:
description: >-
The id of this request, the same req_ value as the X-Request-ID
response header. Quote it when you contact support
examples:
- req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: string
type:
description: The error family. It is one value per HTTP status
examples:
- internal
type: string
type: object
ErrorFieldDetail:
description: 'One failing field: its JSON name, why it failed, and what to change.'
properties:
field:
description: The JSON name of the failing field, with dots for nested fields
type: string
message:
description: What to change in this field
type: string
reason:
description: >-
Why the field failed: required, invalid_format, out_of_range,
unknown_field, not_allowed or too_long
examples:
- required
type: string
type: object
responses:
Unauthorized:
content:
application/json:
examples:
authentication_required:
summary: The request carried no API key or session token.
value:
code: authentication_required
doc_url: https://docs.scrip.dev/errors#authentication_required
message: The request carried no API key or session token.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: authentication
invalid_api_key:
summary: >-
The API key in the Authorization header is unknown, revoked or
needs rotation.
value:
code: invalid_api_key
doc_url: https://docs.scrip.dev/errors#invalid_api_key
message: >-
The API key in the Authorization header is unknown, revoked or
needs rotation.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: authentication
schema:
$ref: '#/components/schemas/ErrUnauthorizedResponse'
description: The API key is missing or not valid.
headers:
WWW-Authenticate:
$ref: '#/components/headers/WWW-Authenticate'
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
Forbidden:
content:
application/json:
examples:
insufficient_permissions:
summary: >-
Your role or key does not include the capability this endpoint
needs.
value:
code: insufficient_permissions
doc_url: https://docs.scrip.dev/errors#insufficient_permissions
message: >-
Your role or key does not include the capability this endpoint
needs.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: permission
schema:
$ref: '#/components/schemas/ErrForbiddenResponse'
description: The caller is not allowed to do this.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
TooManyRequests:
content:
application/json:
examples:
rate_limit_exceeded:
summary: Your organization sent more requests than the rate limit allows.
value:
code: rate_limit_exceeded
doc_url: https://docs.scrip.dev/errors#rate_limit_exceeded
message: >-
Your organization sent more requests than the rate limit
allows.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: rate_limited
schema:
$ref: '#/components/schemas/ErrTooManyRequestsResponse'
description: >-
Too many requests. Wait the number of seconds in the Retry-After header,
then retry.
headers:
Retry-After:
$ref: '#/components/headers/Retry-After'
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
InternalError:
content:
application/json:
examples:
internal_error:
summary: Scrip hit an unexpected error while handling the request.
value:
code: internal_error
doc_url: https://docs.scrip.dev/errors#internal_error
message: Scrip hit an unexpected error while handling the request.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: internal
schema:
$ref: '#/components/schemas/ErrInternalResponse'
description: >-
Something failed on Scrip's side. Retry the request, and quote
`request_id` if it keeps failing.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
headers:
WWW-Authenticate:
description: >-
The authentication challenge: `Bearer realm="scrip"`. Send your API key
as a bearer token.
schema:
examples:
- Bearer realm="scrip"
type: string
X-RateLimit-Limit:
description: Request ceiling enforced by the API instance that served your request.
schema:
examples:
- 1000
type: integer
X-RateLimit-Remaining:
description: Requests left before the instance that served your request returns 429.
schema:
examples:
- 0
type: integer
X-RateLimit-Reset:
description: >-
Unix time in seconds when the instance that served your request has its
full allowance again.
schema:
examples:
- 1790000000
type: integer
X-Request-ID:
description: >-
The id of this request, the same `req_` value as `request_id` in an
error body. Quote it when you contact support.
schema:
examples:
- req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: string
Retry-After:
description: Seconds to wait before you retry, rounded up to a whole second.
schema:
examples:
- 1
type: integer
securitySchemes:
BearerAuth:
description: 'Send your API key as `Authorization: Bearer `.'
scheme: bearer
type: http
x-default: sk_...
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.