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

# Register a webhook

> Register a public HTTPS receiver. The signing secret is returned only in this response. Matching events from the preceding 24 hours are queued on first registration, capped at 1,000. An agent may have up to five enabled endpoints.




## OpenAPI

````yaml /api-reference/openapi.yaml post /v1/webhooks
openapi: 3.1.0
info:
  title: Relay developer API
  version: '0.1'
  description: >
    Add Relay as a channel for your agent, receive messages, and reply with
    plain HTTPS and JSON. Authenticate every request with an Agent Token unless
    the endpoint is marked public. The postback_interactions sync feature
    controls whether clients render message components interactively; component
    data parts can always be sent.
  x-relay-feature-availability:
    postback_interactions: off-by-default-preview
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://api.relayapp.im
    description: Production
security:
  - agentToken: []
tags:
  - name: Agent
    description: Inspect the agent controlled by the current Agent Token.
  - name: Messages
    description: Send finalized messages, pipe native agent output, and react.
  - name: Groups
    description: Propose consent-based groups and observe their terminal state.
  - name: Events
    description: >
      Receive durable inbound events, either through signed webhook receivers or
      by long-polling `GET /v1/events`. The two modes are mutually exclusive per
      agent, enforced per request; around a webhook registration or disable
      there is a brief transition window in which both paths can observe the
      same events. Delivery is at least once everywhere — always deduplicate by
      `event_id`.
  - name: Pairing
    description: >
      Device-code pairing for terminal bridges: create a pairing code on a
      computer, let the Relay app claim it, and recover the minted Agent Token
      only with that computer's poll credential. The token never travels to the
      phone.
  - name: Public
    description: Read approved Store agents and share profiles without authentication.
paths:
  /v1/webhooks:
    post:
      tags:
        - Events
      summary: Register a webhook
      description: >
        Register a public HTTPS receiver. The signing secret is returned only in
        this response. Matching events from the preceding 24 hours are queued on
        first registration, capped at 1,000. An agent may have up to five
        enabled endpoints.
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreateInput'
      responses:
        '201':
          description: Webhook registered; store the signing secret now.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSecretResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: URL already registered or five enabled endpoints already exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Invalid URL or event filter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/WebhookDeliveryUnavailable'
components:
  schemas:
    WebhookCreateInput:
      type: object
      additionalProperties: false
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          pattern: ^https://
          maxLength: 2048
          description: Public HTTPS receiver URL.
        events:
          type: array
          minItems: 1
          uniqueItems: true
          description: Omit to subscribe to every current event type.
          items:
            $ref: '#/components/schemas/WebhookEventType'
    WebhookSecretResponse:
      type: object
      required:
        - webhook
        - signing_secret
      properties:
        webhook:
          $ref: '#/components/schemas/WebhookEndpoint'
        signing_secret:
          type: string
          pattern: ^whsec_
          description: >-
            Base64-encoded 256-bit HMAC key. Returned only on create or
            rotation.
          example: whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              example: invalid_request
            message:
              type: string
              example: conversation_id is required
    WebhookEventType:
      type: string
      enum:
        - message.received
        - message.edited
        - message.unsent
        - conversation.added
        - conversation.updated
        - conversation.removed
        - reaction.added
        - reaction.removed
        - message.delivered
        - message.read
        - group.invite.joined
        - group.invite.declined
        - group.invite.completed
        - group.invite.expired
    WebhookEndpoint:
      type: object
      required:
        - id
        - url
        - events
        - enabled
        - secret_prefix
        - created_at
        - updated_at
      properties:
        id:
          type: string
          example: wh_01JZWEBHOOK
        url:
          type: string
          format: uri
          example: https://agent.example/webhooks/relay
        events:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: '#/components/schemas/WebhookEventType'
        enabled:
          type: boolean
        secret_prefix:
          type: string
          description: Non-secret prefix for identifying the configured signing key.
          example: whsec_MfKQ9r8G…
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  responses:
    Unauthorized:
      description: Token is absent or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    WebhookDeliveryUnavailable:
      description: Relay's webhook signing service is temporarily unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    agentToken:
      type: http
      scheme: bearer
      description: Agent Token (`rly_live_…`), shown once at agent creation.

````