xavio-in Webhooks API

openapi: 3.2.0
info:
  title: Nafafy Public Webhooks API
  version: 1.0.0
  description: 'Programmatic access to publish stories, manage products and variants, fulfil orders, run bookings and read analytics on Nafafy.


    - **REST** — `Authorization: Bearer nf_live_…` (or `nf_test_…`) with a key of kind **REST API** minted at https://nafafy.com/dashboard/developer. Each Series F operation names the scope it needs (`x-required-scope`); `x:write` implies `x:read`. `customers:pii` and `refunds:write` are standalone and never implied.

    - **MCP** — https://nafafy.com/api/mcp (JSON-RPC 2.0 over HTTP) needs a key of kind **MCP**; a REST key is refused there, and an MCP key is refused on REST (`wrong_kind`).


    Errors use the envelope `components.schemas.V1Error`; branch on `error.code`. Series F operations list every code they can answer in `x-error-codes` and their limit in `x-rate-limit`.'
  contact:
    name: Nafafy support
    url: https://nafafy.com/developers
servers:
- url: https://nafafy.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Webhooks
  description: 'Signed (X-Nafafy-Signature) event deliveries. Event names: components.schemas.WebhookEvent; payloads: GET /api/v1/public/webhook-events.'
paths:
  /api/v1/webhooks:
    get:
      summary: List the host's webhook endpoints (scope webhooks:read)
      tags:
      - Webhooks
      security:
      - bearerAuth: []
      responses:
        '200':
          description: OK
      operationId: getApiV1Webhooks
      x-operation-id-source: derived
    post:
      summary: Register an endpoint (scope webhooks:write). The signing secret is returned once
      tags:
      - Webhooks
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              - events
              properties:
                url:
                  type: string
                  format: uri
                  description: https only
                events:
                  type: array
                  minItems: 1
                  items:
                    $ref: '#/components/schemas/WebhookEvent'
      responses:
        '201':
          description: Created
      operationId: postApiV1Webhooks
      x-operation-id-source: derived
  /api/v1/webhooks/deliveries:
    get:
      summary: List webhook deliveries
      description: 'Every shop where you are owner or admin, newest first. Page with before_id = the previous next_before_id.


        Scope: `webhooks:read`. Rate limit: 120 per minute per credential.'
      tags:
      - Webhooks
      security:
      - bearerAuth:
        - webhooks:read
      x-required-scope: webhooks:read
      x-rate-limit:
        max: 120
        window_sec: 60
        per: credential
      x-error-codes:
        '400':
        - bad_query
        - bad_request
        '401':
        - missing_token
        - malformed_token
        - unknown_token
        - revoked
        - expired
        - account_suspended
        '403':
        - scope_missing
        - wrong_kind
        '404':
        - not_found
        '429':
        - rate_limited
        '500':
        - server
        '503':
        - owner_client_unavailable
        - webhooks_unavailable
      parameters:
      - name: webhook_id
        in: query
        schema:
          type: string
          format: uuid
      - name: status
        in: query
        schema:
          type: string
          enum:
          - pending
          - retrying
          - succeeded
          - failed
          - abandoned
      - name: before_id
        in: query
        schema:
          type: integer
          minimum: 1
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookDelivery'
                  has_more:
                    type: boolean
                  next_before_id:
                    type:
                    - integer
                    - 'null'
        '400':
          description: Bad request. error.code ∈ bad_query | bad_request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Error'
        '401':
          description: Not authenticated. error.code ∈ missing_token | malformed_token | unknown_token | revoked | expired | account_suspended
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Error'
        '403':
          description: Key lacks the scope / wrong key kind. error.code ∈ scope_missing | wrong_kind
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Error'
        '404':
          description: Not found — also the answer for an id that belongs to someone else. error.code ∈ not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Error'
        '429':
          description: Rate limited (Retry-After header). error.code ∈ rate_limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Error'
        '500':
          description: Server error (sanitised; quote request_id). error.code ∈ server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Error'
        '503':
          description: Temporarily unavailable (retry later). error.code ∈ owner_client_unavailable | webhooks_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Error'
      operationId: getApiV1WebhooksDeliveries
      x-operation-id-source: derived
  /api/v1/webhooks/deliveries/{id}/redeliver:
    post:
      summary: Redeliver a webhook delivery
      description: 'Queues the ORIGINAL payload again as a new delivery, sent once with `X-Nafafy-Redelivery: true` and `X-Nafafy-Original-Delivery: `. Allowed from succeeded, failed and abandoned (the dead letter). One queued redelivery per original event, 50 per shop.


        Scope: `webhooks:write`. Rate limit: 30 per minute per credential.'
      tags:
      - Webhooks
      security:
      - bearerAuth:
        - webhooks:write
      x-required-scope: webhooks:write
      x-rate-limit:
        max: 30
        window_sec: 60
        per: credential
      x-error-codes:
        '400':
        - bad_id
        - bad_request
        '401':
        - missing_token
        - malformed_token
        - unknown_token
        - revoked
        - expired
        - account_suspended
        '403':
        - scope_missing
        - wrong_kind
        '404':
        - not_found
        '409':
        - delivery_in_progress
        - webhook_inactive
        - delivery_too_old
        - redelivery_pending
        '429':
        - rate_limited
        - redelivery_backlog_full
        '500':
        - server
        '503':
        - owner_client_unavailable
        - webhooks_unavailable
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          minimum: 1
        description: Delivery id
      responses:
        '202':
          description: Queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookRedelivery'
        '400':
          description: Bad request. error.code ∈ bad_id | bad_request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Error'
        '401':
          description: Not authenticated. error.code ∈ missing_token | malformed_token | unknown_token | revoked | expired | account_suspended
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Error'
        '403':
          description: Key lacks the scope / wrong key kind. error.code ∈ scope_missing | wrong_kind
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Error'
        '404':
          description: Not found — also the answer for an id that belongs to someone else. error.code ∈ not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Error'
        '409':
          description: Conflict with the current state. error.code ∈ delivery_in_progress | webhook_inactive | delivery_too_old | redelivery_pending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Error'
        '429':
          description: Rate limited (Retry-After header). error.code ∈ rate_limited | redelivery_backlog_full
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Error'
        '500':
          description: Server error (sanitised; quote request_id). error.code ∈ server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Error'
        '503':
          description: Temporarily unavailable (retry later). error.code ∈ owner_client_unavailable | webhooks_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Error'
      operationId: postApiV1WebhooksDeliveriesByIdRedeliver
      x-operation-id-source: derived
components:
  schemas:
    V1Error:
      type: object
      description: Every error on /api/v1. Branch on `error.code` (stable), never on `message`. A 5xx never carries database text; quote `request_id` to support. Some codes add safe detail fields (e.g. bad_transition adds from / to / allowed).
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
              - authentication_error
              - permission_error
              - invalid_request_error
              - not_found
              - rate_limited
              - api_error
            code:
              type: string
            message:
              type: string
            param:
              type: string
              description: The offending field or path parameter.
            request_id:
              type: string
              description: req_<32 hex>; also the Xavio-Request-Id header.
          required:
          - type
          - code
          - message
          - request_id
          additionalProperties: true
      required:
      - error
    WebhookDelivery:
      type: object
      description: One delivery. Never carries the signing secret, the ack token or the endpoint URL.
      properties:
        id:
          type: integer
          description: Delivery id (also sent as X-Nafafy-Delivery).
        webhook_id:
          type: string
          format: uuid
        event:
          type: string
        status:
          type: string
          enum:
          - pending
          - retrying
          - succeeded
          - failed
          - abandoned
          description: '`abandoned` is the dead letter: every retry failed. Redeliver to get out of it.'
        attempts:
          type: integer
        last_status:
          type:
          - integer
          - 'null'
          description: Your endpoint's last HTTP status.
        last_error:
          type:
          - string
          - 'null'
          maxLength: 500
          description: At most 500 characters of your endpoint's answer (or the network error).
        next_retry_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        delivered_at:
          type:
          - string
          - 'null'
          format: date-time
        acked_at:
          type:
          - string
          - 'null'
          format: date-time
        redelivery_of:
          type:
          - integer
          - 'null'
          description: 'Set on a redelivery: the original delivery it repeats.'
        payload:
          type: object
          description: 'The body that was signed and sent (`{"truncated": true}` above 64 KB).'
    WebhookEvent:
      type: string
      enum:
      - order.created
      - order.paid
      - order.packed
      - order.shipped
      - order.out_for_delivery
      - order.delivered
      - order.cancelled
      - order.refund.requested
      - order.refund.refunded
      - order.refund.failed
      - order.refund.needs_review
      - order.refund.manual_payout_required
      - order.cod.confirmed
      - order.cod.expired
      - order.cod.cancelled
      - order.cod.review
      - shipment.label_ready
      - manifest.created
      - product.low_stock
      - story.published
      - link.published
      - link.unpublished
      - lead_pipeline.created
      - lead_pipeline.hot
      - lead_pipeline.stage_changed
      - lead_pipeline.note_added
      - lead_pipeline.task_created
      - lead_pipeline.task_completed
      - lead.received
      - cart.updated
      - dot.purchase
      - host.standing_changed
      description: 'Subscribable merchant webhook events. Full payload reference: GET /api/v1/public/webhook-events. "Send test" delivers `webhook.ping` (not subscribable). Removed 2026-10-01 (never emitted; subscribing now 400s): story.expired, lead.created, order.fulfilled, rsvp.created, comment.posted, reaction.created. The Dot pixel purchase is `dot.purchase` (was `order.paid`).'
      x-event-summaries:
        order.created: A new order was placed (status pending).
        order.paid: The order moved to paid.
        order.packed: The order was packed.
        order.shipped: The order was handed to the courier.
        order.out_for_delivery: The parcel is out for delivery.
        order.delivered: The order was delivered.
        order.cancelled: The order was cancelled.
        order.refund.requested: A refund was requested for an order.
        order.refund.refunded: The refund completed.
        order.refund.failed: The refund failed.
        order.refund.needs_review: The refund outcome is uncertain and needs review.
        order.refund.manual_payout_required: The refund must be paid out manually (e.g. COD).
        order.cod.confirmed: The buyer (or seller) confirmed a COD order.
        order.cod.expired: The COD confirmation window lapsed.
        order.cod.cancelled: A COD order was cancelled at confirmation.
        order.cod.review: A COD order was routed to manual review.
        shipment.label_ready: A courier shipping label is ready to print.
        manifest.created: A pickup manifest was created.
        product.low_stock: A product fell to (or below) its low-stock threshold.
        story.published: A story (cluster) was published.
        link.published: Your Nafafy link page went live.
        link.unpublished: Your bio page was taken offline.
        lead_pipeline.created: A lead entered your CRM pipeline.
        lead_pipeline.hot: A lead became hot.
        lead_pipeline.stage_changed: A lead moved pipeline stage.
        lead_pipeline.note_added: A note was added to a lead.
        lead_pipeline.task_created: A follow-up task was created on a lead.
        lead_pipeline.task_completed: A lead task was completed.
        lead.received: Your Dot pixel recorded a lead event.
        cart.updated: Your Dot pixel recorded an add-to-cart.
        dot.purchase: Your Dot pixel recorded a purchase on YOUR site.
        host.standing_changed: Your shop's standing changed.
    WebhookRedelivery:
      type: object
      properties:
        object:
          type: string
          enum:
          - webhook_redelivery
        delivery_id:
          type: integer
        redelivery_of:
          type: integer
        webhook_id:
          type: string
          format: uuid
        event:
          type: string
        status:
          type: string
          enum:
          - pending
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: nf_live_<32-char> | nf_test_<64-char>