> ## Documentation Index
> Fetch the complete documentation index at: https://docs.replo.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a webhook endpoint

> **Beta** — this endpoint may change before general availability.



## OpenAPI

````yaml /api-reference/openapi.json post /webhook-endpoints
openapi: 3.1.0
info:
  title: Replo Public API
  version: '2026-11-17'
servers:
  - url: https://api.replo.app/v1
security: []
paths:
  /webhook-endpoints:
    post:
      tags:
        - Webhook-endpoints
      summary: Add a webhook endpoint
      description: '**Beta** — this endpoint may change before general availability.'
      operationId: webhookEndpoints.create
      parameters:
        - name: Replo-Api-Version
          in: header
          required: true
          schema:
            type: string
            enum:
              - '2026-11-17'
          description: The public API version to use for this request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                projectId:
                  type: string
                  format: uuid
                  description: Project to send events for.
                url:
                  type: string
                  maxLength: 2048
                  format: uri
                  description: Public https URL that receives a signed POST for each event.
                description:
                  type:
                    - string
                    - 'null'
                  maxLength: 255
                  description: A note for people reading the endpoint list.
                events:
                  type: array
                  items:
                    type: string
                    enum:
                      - order.paid
                      - order.updated
                      - order.refunded
                      - order.cancelled
                      - fulfillment.created
                      - fulfillment.updated
                      - fulfillment.cancelled
                      - shipping_label.purchased
                      - shipping_label.voided
                  maxItems: 20
                  description: >-
                    Event types to send, e.g. `order.paid`. An empty list sends
                    every event type.
              required:
                - projectId
                - url
                - events
              additionalProperties: false
      responses:
        '201':
          description: Add a webhook endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointWithSecret'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/InvalidCredentials'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - bearerAuth: []
components:
  schemas:
    WebhookEndpointWithSecret:
      type: object
      properties:
        id:
          type: string
          format: uuid
        projectId:
          type: string
          format: uuid
        url:
          type: string
          maxLength: 2048
          format: uri
        description:
          type:
            - string
            - 'null'
          maxLength: 255
        events:
          type: array
          items:
            type: string
            enum:
              - order.paid
              - order.updated
              - order.refunded
              - order.cancelled
              - fulfillment.created
              - fulfillment.updated
              - fulfillment.cancelled
              - shipping_label.purchased
              - shipping_label.voided
        apiVersion:
          type: string
        enabled:
          type: boolean
        disabledReason:
          type:
            - string
            - 'null'
        createdAt:
          type: string
        updatedAt:
          type: string
        object:
          type: string
          enum:
            - webhook_endpoint
        secret:
          type: string
          description: >-
            The signing secret (`whsec_…`). Returned only when the endpoint is
            created and when the secret is rotated.
      required:
        - id
        - projectId
        - url
        - description
        - events
        - apiVersion
        - enabled
        - disabledReason
        - createdAt
        - updatedAt
        - object
        - secret
    PublicApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            doc_url:
              type: string
            issues:
              type: array
              items:
                type: object
                properties:
                  param:
                    type:
                      - string
                      - 'null'
                    description: >-
                      Dotted path to the failing field within the request body,
                      query or path, e.g. "name" or "variants.0.available"; null
                      when the rule covers the whole input.
                  message:
                    type: string
                    description: Why the field was rejected.
                required:
                  - param
                  - message
              description: >-
                Present on an invalid_request whose input failed validation:
                each failing field and why, at most 10.
          required:
            - code
            - message
            - doc_url
      required:
        - error
  responses:
    InvalidRequest:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiError'
    InvalidCredentials:
      description: >-
        Missing or invalid Replo Public API token. Send an active key as
        `Authorization: Bearer replo_sk_...`; if it was revoked, create a new
        key in Replo Settings.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiError'
    Forbidden:
      description: >-
        You are not authorized to access this resource. Ask a workspace owner to
        perform this action or to grant the key's creator access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiError'
    NotFound:
      description: >-
        Not Found. The resource may not exist, this key may lack the required
        scope, or the key's creator may have lost access. Check the key's scopes
        in Replo Settings and the creator's project or workspace access; a
        workspace owner can grant access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiError'
    Conflict:
      description: The resource is in a conflicting state.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiError'
    PayloadTooLarge:
      description: File content exceeds the 10 MiB limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiError'
    RateLimitExceeded:
      description: >-
        Too many requests. Please retry after the time indicated by the
        Retry-After header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiError'
    InternalError:
      description: An internal error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiError'
    ServiceUnavailable:
      description: Service temporarily unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.