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

# Create a webhook endpoint

> Creates a webhook endpoint. We send a signed HTTPS POST to url for each event type you subscribe to, following the Standard Webhooks format (webhook-id, webhook-timestamp and webhook-signature headers). The response includes the signing secret, shown only once: store it now. A workspace can have at most 5 endpoints, enabled or not. The URL must be https and reachable from the internet; private addresses are refused with 422 webhook_url_rejected. Events have no guaranteed order and can be delivered more than once: use the webhook-id header to deduplicate, and GET /pretests/{id} for the current state.

Requires the `webhooks:manage` scope.



## OpenAPI

````yaml /api-reference/openapi.json post /webhook-endpoints
openapi: 3.1.0
info:
  title: Unite API
  version: 1.0.0
  description: >-
    Run ad pre-tests from your own systems: upload a creative, create a
    pre-test, and read its result and PDF report. Every request needs an API key
    sent as a Bearer token. Every response carries an X-Request-Id header.
servers:
  - url: https://myunite.ai/api/v1
security:
  - bearerAuth: []
tags:
  - name: Catalog
    description: What you can send when you create a pre-test.
  - name: Uploads
    description: Send creative files.
  - name: Pretests
    description: Create pre-tests and read their results.
  - name: Quota
    description: How many pre-tests you can still run.
  - name: Webhooks
    description: Manage the endpoints that are notified when a pre-test changes.
paths:
  /webhook-endpoints:
    post:
      tags:
        - Webhooks
      summary: Create a webhook endpoint
      description: >-
        Creates a webhook endpoint. We send a signed HTTPS POST to url for each
        event type you subscribe to, following the Standard Webhooks format
        (webhook-id, webhook-timestamp and webhook-signature headers). The
        response includes the signing secret, shown only once: store it now. A
        workspace can have at most 5 endpoints, enabled or not. The URL must be
        https and reachable from the internet; private addresses are refused
        with 422 webhook_url_rejected. Events have no guaranteed order and can
        be delivered more than once: use the webhook-id header to deduplicate,
        and GET /pretests/{id} for the current state.


        Requires the `webhooks:manage` scope.
      operationId: createWebhookEndpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookEndpointRequest'
      responses:
        '201':
          description: The endpoint, with its signing secret.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointCreated'
        '400':
          description: 'Error. Possible codes: invalid_request.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            Error. Possible codes: invalid_api_key, api_key_revoked,
            api_key_expired.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Error. Possible codes: feature_not_enabled, key_owner_not_member,
            insufficient_scope.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            Error. Possible codes: invalid_request, webhook_url_rejected,
            webhook_endpoint_limit.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Error. Possible codes: rate_limited.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 'Error. Possible codes: internal_error.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CreateWebhookEndpointRequest:
      type: object
      properties:
        url:
          type: string
          maxLength: 2048
          description: >-
            HTTPS address that receives the events. It must be reachable from
            the internet; private addresses are refused.
        events:
          minItems: 1
          type: array
          items:
            type: string
            enum:
              - pretest.completed
              - pretest.failed
              - pretest.report_ready
          description: Event types this endpoint receives. At least one, without repeats.
          uniqueItems: true
        description:
          description: Free text to tell your endpoints apart.
          type: string
          maxLength: 200
      required:
        - url
        - events
      additionalProperties: false
    WebhookEndpointCreated:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          const: webhook_endpoint
        url:
          type: string
        description:
          type:
            - string
            - 'null'
        events:
          type: array
          items:
            type: string
            enum:
              - pretest.completed
              - pretest.failed
              - pretest.report_ready
        status:
          type: string
          enum:
            - enabled
            - disabled
          description: A disabled endpoint receives no events.
        disabledReason:
          description: >-
            Why the endpoint was disabled: gone when your server answered 410 to
            a delivery, or creator_removed when the member who created the
            endpoint left the workspace. Null while enabled.
          type:
            - string
            - 'null'
        createdAt:
          type: string
          description: ISO 8601 UTC.
        secret:
          type: string
          description: >-
            Signing secret (whsec_...). It is shown only in this response: store
            it now. Use it to verify the webhook-signature header.
      required:
        - id
        - object
        - url
        - description
        - events
        - status
        - disabledReason
        - createdAt
        - secret
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - invalid_api_key
                - api_key_revoked
                - api_key_expired
                - insufficient_scope
                - feature_not_enabled
                - key_owner_not_member
                - rate_limited
                - concurrency_limit
                - invalid_request
                - idempotency_key_required
                - idempotency_conflict
                - idempotency_key_retired
                - upload_not_found
                - upload_invalid
                - file_too_large
                - video_too_long
                - invalid_ooh_format
                - invalid_placement
                - brand_not_found
                - quota_exhausted
                - not_found
                - report_not_ready
                - webhook_url_rejected
                - webhook_endpoint_limit
                - internal_error
              description: >-
                Stable machine-readable code. Branch on this, not on the
                message.
            message:
              type: string
              description: Human-readable explanation in English. Its wording can change.
            requestId:
              type: string
              description: >-
                Same value as the X-Request-Id response header. Quote it when
                you contact support.
            docUrl:
              type: string
              description: Page that explains this code.
            param:
              description: >-
                The field, query parameter or header the error refers to, when
                there is one.
              type: string
          required:
            - code
            - message
            - requestId
            - docUrl
      required:
        - error
  headers:
    X-Request-Id:
      description: >-
        Identifier of this request. Quote it when you contact support. It is
        also in error.requestId.
      schema:
        type: string
    RateLimit-Limit:
      description: >-
        Requests allowed per minute for this key and bucket: 600 for reads, 60
        for writes. Sent on responses once the key is accepted. On 401 errors
        and on 403 errors raised while the key is checked they may be absent.
      schema:
        type: integer
    RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
    RateLimit-Reset:
      description: Seconds until the oldest counted request leaves the window.
      schema:
        type: integer
    Retry-After:
      description: Seconds to wait before you try again.
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key, sent as `Authorization: Bearer unite_live_...`. Create keys in
        the workspace settings.

````

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