openapi: 3.0.3
info:
  title: RecallMatch Webhooks API
  version: 1.0.0
  description: Signed, retryable recall.match.created delivery for monitored catalogs.
servers:
  - url: https://apirecallmatch.vedranv.com
paths:
  /v1/webhooks:
    post:
      summary: Create a webhook subscription
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhook'
      responses:
        '201':
          description: Created. The signing secret is returned once.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/CreateWebhookResponse'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '422': {$ref: '#/components/responses/ValidationError'}
    get:
      summary: List webhook subscriptions
      security: [{bearerAuth: []}]
      responses:
        '200':
          description: Tenant-owned subscriptions
          content:
            application/json:
              schema:
                type: object
                required: [webhooks]
                properties:
                  webhooks:
                    type: array
                    items: {$ref: '#/components/schemas/Webhook'}
  /v1/webhooks/{webhook_id}:
    delete:
      summary: Delete a webhook subscription
      security: [{bearerAuth: []}]
      parameters:
        - {$ref: '#/components/parameters/WebhookID'}
      responses:
        '204': {description: Deleted}
        '404': {$ref: '#/components/responses/NotFound'}
components:
  parameters:
    WebhookID:
      name: webhook_id
      in: path
      required: true
      schema: {type: string, format: uuid}
  schemas:
    CreateWebhook:
      type: object
      additionalProperties: false
      required: [url]
      properties:
        url: {type: string, format: uri, pattern: '^https://'}
        events:
          type: array
          minItems: 1
          maxItems: 1
          uniqueItems: true
          items: {type: string, enum: [recall.match.created]}
    Webhook:
      type: object
      required: [id, url, events, status, created_at, updated_at]
      properties:
        id: {type: string, format: uuid}
        url: {type: string, format: uri}
        events: {type: array, items: {type: string, enum: [recall.match.created]}}
        status: {type: string, enum: [active, disabled]}
        last_error: {type: string}
        failure_count: {type: integer, minimum: 0}
        created_at: {type: string, format: date-time}
        updated_at: {type: string, format: date-time}
    CreateWebhookResponse:
      type: object
      required: [webhook, secret]
      properties:
        webhook: {$ref: '#/components/schemas/Webhook'}
        secret: {type: string, description: Returned only once; use it to verify HMAC signatures.}
  responses:
    Unauthorized:
      description: A valid bearer API key is required.
    NotFound:
      description: Resource not found for this tenant.
    ValidationError:
      description: Request validation failed.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: RecallMatch API key
x-recallmatch-webhook:
  event: recall.match.created
  signature: 'HMAC-SHA256 over <X-RecallMatch-Timestamp>.<raw-body>, sent as X-RecallMatch-Signature: sha256=<hex>'
  retries: 'At most 10 attempts; 30s, 2m, 10m, then 1h backoff.'
  disclaimer: An automated signal from official recall data, not a safety certification.