FirstPromoter Webhooks API

openapi: 3.2.0
info:
  title: FirstPromoter Admin Webhooks API
  version: 2.0.0
  description: Manage webhook subscriptions and inspect deliveries.
servers:
- url: https://api.firstpromoter.com/api/v2/company
  description: Production server
security:
- BearerAuth: []
tags:
- name: Webhooks
paths:
  /webhooks:
    get:
      summary: List webhook subscriptions
      tags:
      - Webhooks
      description: "Returns a paginated list of all webhook subscriptions for your account, ordered by creation date descending. \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/webhooks`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: per_page
        in: query
        schema:
          type: integer
          default: 25
        description: Number of results per page.
      - name: page
        in: query
        schema:
          type: integer
          default: 1
        description: Page number.
      responses:
        '200':
          description: Paginated list of webhook subscriptions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebhookSubscription'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    post:
      summary: Create a webhook subscription
      tags:
      - Webhooks
      description: "Creates a new webhook subscription. The `secret_key` is auto-generated and returned only in this response — store it immediately. \n <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/webhooks`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscriptionInput'
      responses:
        '201':
          description: Subscription created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /webhooks/event_types:
    get:
      summary: List supported event types
      tags:
      - Webhooks
      description: "Returns a sorted list of all event type strings that can be subscribed to. Use these values in the `event_types` array when creating or updating a subscription. \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/webhooks/event_types`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: List of supported event types
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: string
                    example:
                    - commission.created
                    - commission.deleted
                    - commission.updated
                    - contract_document.signed
                    - payments_batch.created
                    - payments_batch.deleted
                    - payments_batch.updated
                    - payout.commissions.created
                    - payout.commissions.deleted
                    - payout.commissions.updated
                    - payout.created
                    - payout.deleted
                    - payout.updated
                    - payout_method.created
                    - payout_method.deleted
                    - payout_method.updated
                    - promoter.balance.updated
                    - promoter.created
                    - promoter.deleted
                    - promoter.profile.updated
                    - promoter.updated
                    - promoter_campaign.created
                    - promoter_campaign.deleted
                    - promoter_campaign.updated
                    - referral.created
                    - referral.deleted
                    - referral.moved
                    - referral.updated
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /webhooks/test:
    post:
      summary: Send a test webhook delivery
      tags:
      - Webhooks
      description: "Sends a sample payload for the given event type to the specified URL immediately. Useful for verifying that your endpoint is reachable and processing payloads correctly before creating a subscription. \n\n The signature in the test request is generated with a random secret (not a saved subscription's secret), so signature verification will fail — this is expected during testing. \n\n Returns the HTTP status and body received from your endpoint. \n <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/webhooks/test`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              - event_type
              properties:
                url:
                  type: string
                  format: uri
                  description: The URL to send the test payload to. Must be a public URL — requests to private/internal networks are blocked.
                event_type:
                  type: string
                  description: The event type to generate a sample payload for. Use any value from the `event_types` endpoint.
                basic_auth_user:
                  type: string
                  description: HTTP Basic Auth username to include in the test request.
                basic_auth_password:
                  type: string
                  description: HTTP Basic Auth password to include in the test request.
                headers:
                  type: object
                  description: Custom HTTP headers to include in the test request.
                  additionalProperties:
                    type: string
                  example:
                    X-Api-Key: my-secret-token
      responses:
        '200':
          description: Test delivery sent — response mirrors what your endpoint returned.
        '400':
          description: Invalid URL (private network or malformed URI)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /webhooks/{id}:
    get:
      summary: Get a webhook subscription
      tags:
      - Webhooks
      description: "Returns the details of a single webhook subscription. \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/webhooks/{id}`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: ID of the webhook subscription.
      responses:
        '200':
          description: Webhook subscription details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
    put:
      summary: Update a webhook subscription
      tags:
      - Webhooks
      description: "Updates an existing webhook subscription. Only fields you include in the request body are changed. \n <Tip>**HTTP Request** <br/>`PUT https://api.firstpromoter.com/api/v2/company/webhooks/{id}`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: ID of the webhook subscription.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscriptionInput'
      responses:
        '200':
          description: Subscription updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete a webhook subscription
      tags:
      - Webhooks
      description: "Permanently deletes a webhook subscription and all its delivery records. \n <Tip>**HTTP Request** <br/>`DELETE https://api.firstpromoter.com/api/v2/company/webhooks/{id}`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: ID of the webhook subscription.
      responses:
        '200':
          description: Subscription deleted successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
components:
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error description.
        code:
          type: string
          description: Machine-readable error code.
    WebhookSubscriptionInput:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: The HTTPS URL that will receive webhook payloads. Required when creating.
        event_types:
          type: array
          items:
            type: string
          description: One or more event type strings to subscribe to. Required when creating. Use the `event_types` endpoint to list all supported values.
          example:
          - referral.created
          - commission.created
        active:
          type: boolean
          description: Enable or pause delivery. Defaults to `true`.
        timeout:
          type: integer
          description: Request timeout in seconds. Must be 1–120. Defaults to 30.
          minimum: 1
          maximum: 120
        max_retries:
          type: integer
          description: Automatic retry count for failed deliveries. Must be 0–10. Defaults to 3.
          minimum: 0
          maximum: 10
        description:
          type: string
          description: Optional human-readable label.
        campaign_ids:
          type: array
          items:
            type: integer
          description: Restrict this subscription to events from specific campaigns. Pass `[1]` (the default) to receive events from all campaigns.
          example:
          - 1
        headers:
          type: object
          description: Custom HTTP headers to include in every delivery request.
          additionalProperties:
            type: string
          example:
            Authorization: Bearer my-token
        basic_auth_user:
          type: string
          description: HTTP Basic Auth username. Must be set together with `basic_auth_password`.
        basic_auth_password:
          type: string
          description: HTTP Basic Auth password. Write-only — never returned in responses. Encrypted at rest.
    WebhookSubscription:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the subscription.
        url:
          type: string
          format: uri
          description: The endpoint URL that receives webhook payloads.
        description:
          type:
          - string
          - 'null'
          description: Optional human-readable label for this subscription.
        event_types:
          type: array
          items:
            type: string
          description: Event type strings this subscription is listening to.
          example:
          - referral.created
          - commission.created
        campaign_ids:
          type: array
          items:
            type: integer
          description: Campaign IDs that trigger this subscription. `[1]` means all campaigns.
          example:
          - 1
        active:
          type: boolean
          description: Whether delivery is enabled. Set to `false` to pause without deleting.
        timeout:
          type: integer
          description: 'Request timeout in seconds. Must be between 1 and 120. Default: 30.'
          minimum: 1
          maximum: 120
        max_retries:
          type: integer
          description: 'Number of times a failed delivery is automatically retried. Must be between 0 and 10. Default: 3.'
          minimum: 0
          maximum: 10
        headers:
          type: object
          description: Custom HTTP headers sent with every delivery request.
          additionalProperties:
            type: string
          example:
            Authorization: Bearer my-token
        basic_auth_user:
          type:
          - string
          - 'null'
          description: HTTP Basic Auth username sent with every delivery. `null` if not configured.
        basic_auth_enabled:
          type: boolean
          description: '`true` when both a Basic Auth username and password are set on this subscription.'
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the subscription was created.
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last update.
  parameters:
    AccountId:
      name: Account-ID
      in: header
      required: true
      description: Account ID. Found in your FirstPromoter dashboard under Settings → Integrations.
      schema:
        type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer