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

# Register an inbound webhook subscription on a connection

> Registers an inbound-webhook subscription on an integration connection. External services (the connection's upstream) deliver events into Marfa by POSTing to the public receipt URL the platform exposes per subscription. Signature verification uses the adapter named in `webhook_verification.method` on the connection's manifest — `hmac-sha256`, `slack`, `stripe`, or `github`.

The `secret` is returned **once** in the creation response — store it then; subsequent reads redact it. See [Inbound webhooks](/api/inbound-webhooks).



## OpenAPI

````yaml /openapi.json post /connections/{id}/inbound-webhooks
openapi: 3.1.0
info:
  title: Marfa API
  version: 4.2.0
  description: Typed data layer for structured personal data
servers: []
security: []
paths:
  /connections/{id}/inbound-webhooks:
    post:
      tags:
        - Inbound Webhooks
      summary: Register an inbound webhook subscription on a connection
      description: >-
        Registers an inbound-webhook subscription on an integration connection.
        External services (the connection's upstream) deliver events into Marfa
        by POSTing to the public receipt URL the platform exposes per
        subscription. Signature verification uses the adapter named in
        `webhook_verification.method` on the connection's manifest —
        `hmac-sha256`, `slack`, `stripe`, or `github`.


        The `secret` is returned **once** in the creation response — store it
        then; subsequent reads redact it. See [Inbound
        webhooks](/api/inbound-webhooks).
      parameters:
        - schema:
            type: string
          required: true
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                external_service_id:
                  type: string
                events:
                  type: array
                  items:
                    type: string
                  minItems: 1
              required:
                - events
      responses:
        '201':
          description: >-
            Subscription created. The `secret` field is returned ONCE;
            subsequent reads redact it.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  tenant_id:
                    type: string
                  connection_id:
                    type: string
                  external_service_id:
                    type: string
                  secret_redacted:
                    type: string
                  verification_method:
                    type: string
                    enum:
                      - hmac-sha256
                      - slack
                      - stripe
                      - github
                  verification_adapter_id:
                    type: string
                  events:
                    type: array
                    items:
                      type: string
                  disabled:
                    type: boolean
                  created_at:
                    type: string
                  updated_at:
                    type: string
                  secret:
                    type: string
                required:
                  - id
                  - connection_id
                  - secret_redacted
                  - verification_method
                  - events
                  - disabled
                  - created_at
                  - updated_at
                  - secret
        '400':
          description: Validation error or invalid manifest
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - validation_error
                          - missing_required_field
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties:
                          nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - unauthorized
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties:
                          nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        '403':
          description: Caller cannot manage this connection
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - forbidden
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties:
                          nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        '404':
          description: Connection not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - connection_not_found
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties:
                          nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key or OAuth Token
      description: Pass an API key (marfa_k1_...) or OAuth access token (marfa_at_...)

````