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

# Receive events pushed by partner (partner → Barker)

> The partner POSTs events to Barker.
- Must be HMAC-SHA256 signed (using the inbound secret configured in portal)
- Must include the `Idempotency-Key` header — duplicates return 200 without re-processing




## OpenAPI

````yaml /openapi.yaml post /api/partner/webhooks/inbound
openapi: 3.0.3
info:
  title: Barker Yield Engine API
  version: 1.0.0
  description: >
    Yield-embed API for partners (wallets, payment apps).


    Authentication: `X-Api-Key` header, self-served from portal.barker.money.

    Revenue: 100% via on-chain fee split inside the engine contract — calling
    this API is free.

    Rate limit: 1000 req/min for production keys (`bk_live_*`), 100 req/min for
    sandbox keys (`bk_test_*`). Anti-abuse, not usage billing.


    Two integration modes — same engines, same key, same fee split, different UI
    surface:
      - Embed (iframe): drop-in UI hosted at app.barker.money, no contract calls in your code.
      - Headless API: your UI calls BarkerEngine (ERC-4626) directly with the user's wallet; this API serves metadata, position, fee stats, and webhooks.
    See https://docs.barker.money/integration-modes for the decision guide.


    Error responses share `{ success: false, code, message }`. Full code catalog
    at https://docs.barker.money/error-codes.
  contact:
    name: Barker
    url: https://docs.barker.money
servers:
  - url: https://api.barker.money
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: products
    description: Partner products (engines) — read access
  - name: position
    description: User position queries
  - name: webhooks
    description: Event subscriptions and callbacks
paths:
  /api/partner/webhooks/inbound:
    post:
      tags:
        - webhooks
      summary: Receive events pushed by partner (partner → Barker)
      description: >
        The partner POSTs events to Barker.

        - Must be HMAC-SHA256 signed (using the inbound secret configured in
        portal)

        - Must include the `Idempotency-Key` header — duplicates return 200
        without re-processing
      parameters:
        - in: header
          name: X-Barker-Event
          required: true
          schema:
            type: string
            example: partner.user.created
        - in: header
          name: X-Barker-Signature
          required: true
          schema:
            type: string
            description: hex(hmac_sha256(secret, raw_body))
        - in: header
          name: Idempotency-Key
          required: true
          schema:
            type: string
            example: evt_2026_05_03_xxxxx
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboundWebhookEvent'
      responses:
        '200':
          description: Received (includes duplicates)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  event_id:
                    type: integer
                  duplicate:
                    type: boolean
        '400':
          description: Invalid event / missing idempotency-key
        '401':
          description: Signature mismatch
        '500':
          description: Server error
components:
  schemas:
    InboundWebhookEvent:
      type: object
      required:
        - event_type
        - occurred_at
        - data
      properties:
        event_type:
          type: string
          enum:
            - partner.user.created
            - partner.user.kyc_updated
            - partner.reconciliation.confirmed
        occurred_at:
          type: string
          format: date-time
        data:
          type: object
          additionalProperties: true
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key

````