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

# Register a webhook endpoint

> The endpoint's signing `secret` is included in this response only; it
cannot be read again later, but can be rotated at any time. An app may
hold a small fixed number of endpoints (403 when exceeded), and an
approved app needs a Synci plan first (402).



## OpenAPI

````yaml /openapi/managed.json post /webhooks
openapi: 3.1.0
info:
  title: Synci
  version: '1.0'
  description: >-
    Register and manage the end users your Managed app pays for. Authenticate
    with HTTP Basic using your app's client id and client secret. See the
    Managed apps guide for the full flow.
servers:
  - url: https://api.synci.io/managed/v1
security:
  - basicAuth: []
tags:
  - name: Managed Users
  - name: Managed Connections
  - name: Managed Webhooks
paths:
  /webhooks:
    post:
      tags:
        - Managed Webhooks
      summary: Register a webhook endpoint
      description: |-
        The endpoint's signing `secret` is included in this response only; it
        cannot be read again later, but can be rotated at any time. An app may
        hold a small fixed number of endpoints (403 when exceeded), and an
        approved app needs a Synci plan first (402).
      operationId: managed.webhooks.store
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAppWebhookEndpointRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
        '422':
          $ref: '#/components/responses/ValidationException'
components:
  schemas:
    CreateAppWebhookEndpointRequest:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: |-
            The HTTPS URL that will receive event deliveries for every user
            your app manages.
          maxLength: 512
        description:
          type:
            - string
            - 'null'
          description: Optional label to help you identify the endpoint.
          maxLength: 255
        enabled:
          type: boolean
          description: Whether the endpoint receives deliveries. Defaults to true.
        events:
          type: array
          description: |-
            The event types this endpoint should receive: the bank-data events
            (`transactions.created`, `transactions.updated`, `balance.updated`,
            `holdings.updated`, `account.*`), the connection lifecycle
            (`connection.*`) and `portal.user.verified`. Legacy `bank_account.*`
            aliases are not available on this surface.
          items:
            type: string
            enum:
              - transactions.created
              - transactions.updated
              - balance.updated
              - holdings.updated
              - account.created
              - account.updated
              - account.deleted
              - connection.created
              - connection.activated
              - connection.reauthorized
              - connection.expiring
              - connection.expired
              - connection.failing
              - connection.recovered
              - connection.disabled
              - connection.deleted
              - portal.user.verified
          minItems: 1
        omit_sensitive_identifiers:
          type: boolean
          description: |-
            When true, sensitive account identifiers (IBAN/BBAN) are omitted
            from delivered payloads. They are omitted regardless unless your
            app has been approved for the `sensitive:read` scope.
        financial_accounts:
          type: string
          description: |-
            Not available on app-level endpoints: an app receives events for
            every user it manages, so a per-account filter has no meaning here.
        payload_version:
          type: string
          description: |-
            Not available on app-level endpoints: deliveries always use the
            current (v2) payload shape.
        type:
          type: string
      required:
        - url
        - events
      title: CreateAppWebhookEndpointRequest
  responses:
    ValidationException:
      description: Validation error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: Errors overview.
              errors:
                type: object
                description: A detailed description of each field that failed validation.
                additionalProperties:
                  type: array
                  items:
                    type: string
            required:
              - message
              - errors
  securitySchemes:
    basicAuth:
      type: http
      description: |-
        **Username = your client id. Password = your client secret.**

        So the base64-encoded `username:password` described below is
        `client_id:client_secret`:

        ```
        Authorization: Basic base64(YOUR_CLIENT_ID:YOUR_CLIENT_SECRET)
        ```

        Most HTTP clients build that header for you:

        ```bash
        curl -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
             https://api.synci.io/managed/v1/users
        ```

        Both values come from **Developers → Apps → your app**. The
        secret is shown once at creation and is prefixed `oac_`.
      scheme: basic

````

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