AffiliateRail Webhook endpoints API

openapi: 3.2.0
info:
  title: Affiliaterail Com Webhook endpoints API
  version: '2026-08-21'
  description: 'Operations tagged Webhook endpoints across 2 of this provider''s published API definitions: affiliaterail-com-docs-openapi.json, affiliaterail-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.affiliaterail.com
  description: Production
tags:
- name: Webhook Endpoints
paths:
  /v1/webhook_endpoints:
    get:
      tags:
      - Webhook Endpoints
      summary: List webhook endpoints
      description: 'The event catalogue, payload examples and signature verification are published at https://app.affiliaterail.com/webhooks/llms.txt.


        **Scope:** `read`'
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          example: prg_7uSyy9FqVLCFWrdPeZaK
          description: Required on every list
        required: true
        description: Required on every list
        name: program_id
        in: query
      - schema:
          type: string
          example: '25'
          description: 1 to 100, default 25
        required: false
        description: 1 to 100, default 25
        name: limit
        in: query
      - schema:
          type: string
          description: Object id; returns the page after it (older)
        required: false
        description: Object id; returns the page after it (older)
        name: starting_after
        in: query
      - schema:
          type: string
          description: Object id; returns the page before it (newer)
        required: false
        description: Object id; returns the page before it (newer)
        name: ending_before
        in: query
      - schema:
          anyOf:
          - type: string
          - type: array
            items:
              type: string
          description: No relations on this resource
        required: false
        description: No relations on this resource
        name: expand[]
        in: query
      - schema:
          anyOf:
          - type: string
          - type: array
            items:
              type: string
          description: Nothing to include on this resource
        required: false
        description: Nothing to include on this resource
        name: include[]
        in: query
      responses:
        '200':
          description: Endpoints
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointList'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or unknown API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Key lacks the required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such object in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The request was understood and refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited: see Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getV1WebhookEndpoints
      x-operation-id-source: derived
    post:
      tags:
      - Webhook Endpoints
      summary: Create a webhook endpoint
      description: 'HTTPS, public address only. The response carries `secret` exactly once.


        **Scope:** `webhooks:write` (or `write`)'
      security:
      - bearerAuth: []
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointCreate'
      responses:
        '201':
          description: The new endpoint, with its secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or unknown API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Key lacks the required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such object in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The request was understood and refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited: see Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postV1WebhookEndpoints
      x-operation-id-source: derived
    servers:
    - url: https://api.affiliaterail.com
      description: Production
  /v1/webhook_endpoints/{id}:
    get:
      tags:
      - Webhook Endpoints
      summary: Retrieve a webhook endpoint
      description: '**Scope:** `read`'
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          pattern: ^(sample_)?whe_
          example: whe_7uSyy9FqVLCFWrdPeZaK
          description: Prefixed id (`whe_…`)
        required: true
        description: Prefixed id (`whe_…`)
        name: id
        in: path
      responses:
        '200':
          description: The endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or unknown API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Key lacks the required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such object in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The request was understood and refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited: see Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getV1WebhookEndpointsById
      x-operation-id-source: derived
    post:
      tags:
      - Webhook Endpoints
      summary: Update a webhook endpoint
      description: '**Scope:** `webhooks:write` (or `write`)'
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          pattern: ^(sample_)?whe_
          example: whe_7uSyy9FqVLCFWrdPeZaK
          description: Prefixed id (`whe_…`)
        required: true
        description: Prefixed id (`whe_…`)
        name: id
        in: path
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointUpdate'
      responses:
        '200':
          description: The updated endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or unknown API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Key lacks the required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such object in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The request was understood and refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited: see Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postV1WebhookEndpointsById
      x-operation-id-source: derived
    delete:
      tags:
      - Webhook Endpoints
      summary: Delete a webhook endpoint
      description: '**Scope:** `webhooks:write` (or `write`)'
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          pattern: ^(sample_)?whe_
          example: whe_7uSyy9FqVLCFWrdPeZaK
          description: Prefixed id (`whe_…`)
        required: true
        description: Prefixed id (`whe_…`)
        name: id
        in: path
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deleted'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or unknown API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Key lacks the required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such object in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The request was understood and refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited: see Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: deleteV1WebhookEndpointsById
      x-operation-id-source: derived
    servers:
    - url: https://api.affiliaterail.com
      description: Production
  /v1/webhook_endpoints/{id}/rotate_secret:
    post:
      tags:
      - Webhook Endpoints
      summary: Rotate the signing secret
      description: 'Deliveries after this call are signed with the new secret, and with the old one as well for 24 hours (two `v1=` entries in `Rail-Signature`), so you can swap at your own pace.


        **Scope:** `webhooks:write` (or `write`)'
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          pattern: ^(sample_)?whe_
          example: whe_7uSyy9FqVLCFWrdPeZaK
          description: Prefixed id (`whe_…`)
        required: true
        description: Prefixed id (`whe_…`)
        name: id
        in: path
      responses:
        '200':
          description: The endpoint, with its new secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or unknown API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Key lacks the required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such object in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The request was understood and refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited: see Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postV1WebhookEndpointsByIdRotateSecret
      x-operation-id-source: derived
    servers:
    - url: https://api.affiliaterail.com
      description: Production
  /v1/webhook_endpoints/{id}/deliveries:
    get:
      tags:
      - Webhook Endpoints
      summary: Recent deliveries
      description: 'The last 50 attempts: status, attempt count, response code, and the exact body we sent.


        **Scope:** `read`'
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          pattern: ^(sample_)?whe_
          example: whe_7uSyy9FqVLCFWrdPeZaK
          description: Prefixed id (`whe_…`)
        required: true
        description: Prefixed id (`whe_…`)
        name: id
        in: path
      responses:
        '200':
          description: Deliveries, newest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {}
                  has_more:
                    type: boolean
                  total_count:
                    type: integer
                required:
                - data
                - has_more
                - total_count
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or unknown API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Key lacks the required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such object in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The request was understood and refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited: see Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getV1WebhookEndpointsByIdDeliveries
      x-operation-id-source: derived
    servers:
    - url: https://api.affiliaterail.com
      description: Production
  /v1/webhook_endpoints/{id}/ping:
    post:
      tags:
      - Webhook Endpoints
      summary: Send a test event
      description: 'Delivers a sample event to the endpoint right now, once, and reports what came back. If it can''t be sent from here straight away, `outcome` is `pending` and `response_status` is null: the delivery is queued and goes out within five minutes, and its result appears in the delivery log. The delivery lands in the log like any other, so you can see exactly what was sent, and it carries both signature schemes.


        **Scope:** `webhooks:write` (or `write`)'
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          pattern: ^(sample_)?whe_
          example: whe_7uSyy9FqVLCFWrdPeZaK
          description: Prefixed id (`whe_…`)
        required: true
        description: Prefixed id (`whe_…`)
        name: id
        in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                event_type:
                  type: string
                  description: Any type from the event catalogue. Defaults to `sale.created`.
      responses:
        '200':
          description: What the one attempt did
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - webhook_ping
                  delivery_id:
                    type: string
                  outcome:
                    type: string
                  response_status:
                    type:
                    - integer
                    - 'null'
                required:
                - object
                - delivery_id
                - outcome
                - response_status
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or unknown API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Key lacks the required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such object in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The request was understood and refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited: see Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postV1WebhookEndpointsByIdPing
      x-operation-id-source: derived
    servers:
    - url: https://api.affiliaterail.com
      description: Production
  /v1/webhook_deliveries/{id}/replay:
    post:
      tags:
      - Webhook Endpoints
      summary: Replay a delivery
      description: 'Queues a fresh delivery carrying the original payload and the original `webhook-id`, so a consumer that de-duplicates is unaffected. The original log row stays exactly as it was.


        **Scope:** `webhooks:write` (or `write`)'
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          pattern: ^(sample_)?whd_
          example: whd_7uSyy9FqVLCFWrdPeZaK
          description: Prefixed id (`whd_…`)
        required: true
        description: Prefixed id (`whd_…`)
        name: id
        in: path
      responses:
        '200':
          description: The queued replay
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - webhook_replay
                  delivery_id:
                    type: string
                    description: The new pending delivery
                  replay_of:
                    type: string
                required:
                - object
                - delivery_id
                - replay_of
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or unknown API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Key lacks the required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such object in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The request was understood and refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited: see Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postV1WebhookDeliveriesByIdReplay
      x-operation-id-source: derived
    servers:
    - url: https://api.affiliaterail.com
      description: Production
  /v1/webhook_events:
    get:
      tags:
      - Webhook Endpoints
      summary: The event catalogue
      description: 'Every event type an endpoint can subscribe to, with a description and an example payload.


        **Scope:** `read`'
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Event types
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                        description:
                          type: string
                        example: {}
                      required:
                      - type
                      - description
                  has_more:
                    type: boolean
                  total_count:
                    type: integer
                required:
                - data
                - has_more
                - total_count
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or unknown API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Key lacks the required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such object in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The request was understood and refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited: see Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getV1WebhookEvents
      x-operation-id-source: derived
    servers:
    - url: https://api.affiliaterail.com
      description: Production
components:
  schemas:
    WebhookEndpointList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEndpoint'
        has_more:
          type: boolean
          description: Pass the last object's id as `starting_after` to fetch the next page
        total_count:
          type: integer
          description: Count of every object matching the filters, ignoring the cursor
      required:
      - data
      - has_more
      - total_count
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
              - authentication_error
              - permission_error
              - invalid_request_error
              - not_found_error
              - conflict_error
              - rate_limit_error
              - plan_error
              - not_implemented_error
              - api_error
            code:
              type: string
            message:
              type: string
            param:
              type: string
          required:
          - type
          - code
          - message
      required:
      - error
    WebhookEndpointCreate:
      type: object
      properties:
        program_id:
          type: string
          pattern: ^(sample_)?prg_
          example: prg_7uSyy9FqVLCFWrdPeZaK
          description: Prefixed id (`prg_…`)
        url:
          type: string
          format: uri
        event_types:
          type: array
          items:
            type: string
          default: []
          description: Empty means every event
      required:
      - program_id
      - url
    WebhookEndpoint:
      type: object
      properties:
        id:
          type: string
          pattern: ^(sample_)?whe_
          example: whe_7uSyy9FqVLCFWrdPeZaK
          description: Prefixed id (`whe_…`)
        object:
          type: string
          enum:
          - webhook_endpoint
        program_id:
          type: string
          pattern: ^(sample_)?prg_
          example: prg_7uSyy9FqVLCFWrdPeZaK
          description: Prefixed id (`prg_…`)
        partner_id:
          type:
          - string
          - 'null'
          pattern: ^(sample_)?part_
          example: part_7uSyy9FqVLCFWrdPeZaK
          description: Prefixed id (`part_…`)
        url:
          type: string
        event_types:
          type: array
          items:
            type: string
        enabled:
          type: boolean
        secret:
          type: string
          description: Shown once, on creation
        created_at:
          type: string
          format: date-time
          example: '2026-08-21T10:15:30.000Z'
          description: ISO-8601, UTC
        updated_at:
          type: string
          format: date-time
          example: '2026-08-21T10:15:30.000Z'
          description: ISO-8601, UTC
      required:
      - id
      - object
      - program_id
      - partner_id
      - url
      - event_types
      - enabled
      - created_at
      - updated_at
    WebhookEndpointUpdate:
      type: object
      properties:
        url:
          type: string
          format: uri
        event_types:
          type: array
          items:
            type: string
        enabled:
          type: boolean
    Deleted:
      type: object
      properties:
        id:
          type: string
          pattern: ^(sample_)?part_
          example: part_7uSyy9FqVLCFWrdPeZaK
          description: Prefixed id (`part_…`)
        object:
          type: string
        deleted:
          type: boolean
          enum:
          - true
      required:
      - id
      - object
      - deleted
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: rail_live_… or rail_test_…
      description: Create keys in Settings → API keys. Each key carries scopes; the docs name the scope every route needs.
x-refined-from:
- affiliaterail-com-docs-openapi.json
- affiliaterail-com-openapi.json