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

# Create Webhook

> Create a webhook subscription for the authenticated team. The full signing secret is returned exactly once in this response — store it now, because every later read returns only a 4-character preview. Creating a webhook is free (0 API credits). A team may have at most 10 active webhooks.



## OpenAPI

````yaml POST /webhooks
openapi: 3.1.0
info:
  title: Webhooks API
  description: >-
    Manage webhook subscriptions as a first-class API resource. Create, list,
    retrieve, update, rotate the signing secret of, test, and delete webhooks;
    list delivery attempts and manually retry failed deliveries. The dashboard
    Webhooks UI calls these exact endpoints — there is no separate code path.
  license:
    name: MIT
  version: 2.0.0
servers:
  - url: https://www.trysignalbase.com/api/v2
security:
  - bearerAuth: []
paths:
  /webhooks:
    post:
      summary: Create Webhook
      description: >-
        Create a webhook subscription for the authenticated team. The full
        signing secret is returned exactly once in this response — store it now,
        because every later read returns only a 4-character preview. Creating a
        webhook is free (0 API credits). A team may have at most 10 active
        webhooks.
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreateRequest'
            example:
              endpoint_url: https://example.com/hooks/signalbase
              event_types:
                - funding.created
                - hiring.created
              filters:
                countries: US,GB
      responses:
        '201':
          description: >-
            Webhook created. data includes the full signing secret (shown only
            on create).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCreateResponse'
              example:
                success: true
                data:
                  id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
                  endpoint_url: https://example.com/hooks/signalbase
                  event_types:
                    - funding.created
                    - hiring.created
                  filters:
                    countries: US,GB
                  active: true
                  created_at: '2026-05-29T10:30:00.000Z'
                  updated_at: '2026-05-29T10:30:00.000Z'
                  last_modified_by: user_2a9f8c7b6d5e4f3a
                  last_modified_via: api
                  secret: 3f9a1c7e-2b4d-4e6a-9f1b-8c2d3e4f5a6b
                  stats:
                    total_deliveries: 0
                    successful_deliveries: 0
                    failed_deliveries: 0
                    last_success_at: null
                    last_failure_at: null
                    consecutive_failures: 0
                meta:
                  endpoint: webhooks.create
                  creditsUsed: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/SubscriptionExpired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    WebhookCreateRequest:
      type: object
      required:
        - endpoint_url
        - event_types
      description: >-
        Field names accept snake_case (canonical) or camelCase (endpointUrl,
        eventTypes).
      properties:
        endpoint_url:
          type: string
          format: uri
          maxLength: 500
          description: >-
            Destination URL. Must be a valid http/https URL of at most 500
            characters. In production, localhost and private/link-local
            addresses are rejected.
          example: https://example.com/hooks/signalbase
        event_types:
          type: array
          description: Event types to subscribe to. Duplicates are removed.
          items:
            $ref: '#/components/schemas/EventType'
          example:
            - funding.created
            - hiring.created
        filters:
          type: object
          description: >-
            Optional string key/value filters that narrow which events are
            delivered. Recognized keys: countries, categories, search, teamSize,
            dateFrom, dateTo, funding, roundFlavor, fundingAmount,
            acquisitionAmount, healthScore. Unrecognized keys are silently
            ignored — note the round-type key is `funding`, not `round`. See the
            Webhooks overview 'Filters' section for value formats.
          additionalProperties:
            type: string
          example:
            countries: US,GB
            funding: seed,series a
    WebhookCreateResponse:
      type: object
      required:
        - success
        - data
        - meta
      properties:
        success:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/Webhook'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    EventType:
      type: string
      description: >-
        Event type a subscription can register for. system.test is accepted but
        only ever delivered by the Send Test Event endpoint; it never fires
        automatically.
      enum:
        - funding.created
        - acquisition.created
        - job_change.created
        - hiring.created
        - new_company.created
        - system.test
    Webhook:
      type: object
      description: >-
        A webhook subscription. List/retrieve/update(no rotation)/delete include
        secret_preview; create and rotate_secret include the full secret
        instead.
      required:
        - id
        - endpoint_url
        - event_types
        - filters
        - active
        - created_at
        - updated_at
        - last_modified_by
        - last_modified_via
        - stats
      properties:
        id:
          type: string
          description: Unique webhook ID (UUID).
        endpoint_url:
          type: string
          format: uri
          description: HTTPS endpoint that receives deliveries.
        event_types:
          type: array
          description: Event types this subscription is registered for.
          items:
            $ref: '#/components/schemas/EventType'
        filters:
          type: object
          description: >-
            Optional string key/value filters that narrow which events are
            delivered. Recognized keys: countries, categories, search, teamSize,
            dateFrom, dateTo, funding, roundFlavor, fundingAmount,
            acquisitionAmount, healthScore. Unrecognized keys are silently
            ignored — note the round-type key is `funding`, not `round`. See the
            Webhooks overview 'Filters' section for value formats.
          additionalProperties:
            type: string
        active:
          type: boolean
          description: >-
            Whether the webhook is active. Soft-deleted webhooks are
            active=false.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        last_modified_by:
          type:
            - string
            - 'null'
          description: >-
            ID of the user who last modified the webhook. Null if created before
            audit columns existed.
        last_modified_via:
          type:
            - string
            - 'null'
          description: Where the last change originated.
          enum:
            - api
            - dashboard
            - null
        secret:
          type: string
          description: >-
            Full HMAC signing secret (UUID). Returned ONLY on create and on
            update with rotate_secret:true.
        secret_preview:
          type: string
          description: >-
            An ellipsis followed by the last 4 characters of the secret (e.g.
            "…5a6b"). Returned on every read instead of the full secret.
        stats:
          $ref: '#/components/schemas/WebhookStats'
    ResponseMeta:
      type: object
      required:
        - endpoint
        - creditsUsed
      properties:
        endpoint:
          type: string
          description: Endpoint identifier (e.g. webhooks.create).
        creditsUsed:
          type: integer
          minimum: 0
          description: API credits consumed by this request.
    ErrorResponse:
      type: object
      required:
        - success
        - error
        - code
      properties:
        success:
          type: boolean
          const: false
        error:
          type: string
          description: Human-readable error message.
        code:
          type: string
          enum:
            - bad_request
            - invalid_api_key
            - subscription_expired
            - not_found
            - conflict
            - rate_limited
            - internal_server_error
            - internal_error
        retryAfter:
          type: integer
          description: >-
            Seconds until a retry is recommended. Present on rate-limit (429)
            responses.
    WebhookStats:
      type: object
      required:
        - total_deliveries
        - successful_deliveries
        - failed_deliveries
        - last_success_at
        - last_failure_at
        - consecutive_failures
      properties:
        total_deliveries:
          type: integer
          minimum: 0
        successful_deliveries:
          type: integer
          minimum: 0
        failed_deliveries:
          type: integer
          minimum: 0
        last_success_at:
          type:
            - string
            - 'null'
          format: date-time
        last_failure_at:
          type:
            - string
            - 'null'
          format: date-time
        consecutive_failures:
          type: integer
          minimum: 0
  responses:
    BadRequest:
      description: >-
        Invalid request body, invalid endpoint URL, invalid event type, or the
        per-team active webhook limit (10) was reached.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: Webhook URL must be a public address
            code: bad_request
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: Invalid API key. No key found.
            code: invalid_api_key
    SubscriptionExpired:
      description: The API key belongs to a team without an active subscription.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: >-
              Subscription expired. Please upgrade your subscription:
              https://www.trysignalbase.com/#pricing
            code: subscription_expired
    RateLimited:
      description: >-
        Rate limit exceeded for this team and endpoint. The response also sets
        X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: Too many requests. Please upgrade your plan or slow down.
            code: rate_limited
            retryAfter: 60
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: An unknown error occurred
            code: internal_error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        Signalbase API key. Include as a Bearer token in the Authorization
        header.

````