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

# Register webhook

> Register the HTTPS endpoint that receives platform event notifications.

Webhook delivery is a platform-wide mechanism; the events you receive depend on the
services enabled for your tenant — for the Account Information Service these are the `ais.*`
events.

The response returns a one-time `signing_secret` — store it; it is shown only once and is
used to verify the `x-hmac-signature` on every delivery.

The endpoint must be publicly reachable over HTTPS.



## OpenAPI

````yaml /platform/services/account-information/openapi.yaml post /api/webhooks
openapi: 3.1.0
info:
  title: Account Information API
  description: >-
    Verify a shopper's bank account — ownership, holder name, and account
    identifiers — through the Hellgate Cloud Platform Account Information
    Service. Create a session, drive the shopper through the bank login with the
    Web SDK, and receive the verified record on your backend.
  version: '1.0'
  contact:
    name: Starfish GmbH & Co. KG
    email: hello@starfish.team
    url: https://hellgate.io
  license:
    name: Hellgate API Terms
    url: https://hellgate.io/terms-and-conditions
servers:
  - url: https://api.eu1.hellgate.cloud
    description: EU1 environment
security:
  - bearerAuth: []
tags:
  - name: Account Information
    description: Create account-check sessions and retrieve the verified record.
  - name: Webhooks
    description: Register an endpoint and receive account-check event notifications.
paths:
  /api/webhooks:
    post:
      tags:
        - Webhooks
      summary: Register webhook
      description: >-
        Register the HTTPS endpoint that receives platform event notifications.


        Webhook delivery is a platform-wide mechanism; the events you receive
        depend on the

        services enabled for your tenant — for the Account Information Service
        these are the `ais.*`

        events.


        The response returns a one-time `signing_secret` — store it; it is shown
        only once and is

        used to verify the `x-hmac-signature` on every delivery.


        The endpoint must be publicly reachable over HTTPS.
      operationId: registerWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterWebhookRequest'
      responses:
        '201':
          description: The webhook was registered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          description: The access token is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            The endpoint URL failed validation (HTTPS and a public host are
            required).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    RegisterWebhookRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: The HTTPS endpoint that receives event notifications.
          example: https://your-backend.example.com/hooks/account-information
      example:
        url: https://your-backend.example.com/hooks/account-information
    Webhook:
      type: object
      required:
        - id
        - created_at
        - url
        - signing_secret
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier for the webhook.
          example: 2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e
        created_at:
          type: string
          format: date-time
          description: When the webhook was registered.
          example: '2026-06-22T09:55:00Z'
        url:
          type: string
          format: uri
          description: The registered endpoint.
          example: https://your-backend.example.com/hooks/account-information
        signing_secret:
          type: string
          description: >-
            The signing secret, returned only once. Store it securely and use it
            to verify the `x-hmac-signature` on every delivery.
          example: whsec_9f8e7d6c5b4a3f2e1d0c
      example:
        id: 2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e
        created_at: '2026-06-22T09:55:00Z'
        url: https://your-backend.example.com/hooks/account-information
        signing_secret: whsec_9f8e7d6c5b4a3f2e1d0c
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: A machine-readable error code.
          example: tenant_not_enabled
        message:
          type: string
          description: A human-readable description of the error.
          example: The Account Information Service is not enabled for this tenant.
      example:
        code: tenant_not_enabled
        message: The Account Information Service is not enabled for this tenant.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        An Account Information–scoped OAuth2 access token obtained from the
        platform Authentication API. Send it as a bearer token on every request.

````