# SMKlog payment-session webhooks — AsyncAPI 3.1.
#
# Generated by scripts/build_api_artifacts.mjs from the webhooks key of the
# live OpenAPI document (https://quote-api.smklog.com/openapi.json); written and published by SMKlog.
asyncapi: '3.1.0'
id: 'urn:com:smklog:quote-api:payment-session-webhooks'
info:
  title: SMKlog payment-session webhooks
  version: '1.5.0'
  description: 'What SMKlog sends to an agent''s endpoint after a payment session is created with a callback_url (createPaymentSession, upsertPaymentSession or updatePaymentSession on https://quote-api.smklog.com): one signed HTTP POST each time the session reaches a new stage, checkout_started, paid, label_ready, delivered, refunded, cancelled. The body is a WebhookEvent whose data is the CheckoutStatus of that moment, so the receiver needs no second call. Retries: after 1, 5, 15, 60 minutes, 4 and 12 hours, 7 attempts in all, with the same id each time. The same events are described from the OpenAPI side under the webhooks key of https://quote-api.smklog.com/openapi.json and, for the receiving server, in https://smklog.com/developers/webhooks-inbound.openapi.json; all three are generated from one source.'
  termsOfService: 'https://smklog.com/terms'
  contact:
    name: SMKlog
    email: 'info@smklog.com'
    url: 'https://smklog.com/developers/'
  tags:
    - name: Webhooks
      description: Signed HTTP POSTs to the callback_url of a payment session
    - name: Payments
      description: The stages of a checkout a human completes on smklog.com
  externalDocs:
    description: 'Webhooks guide: setup, events, delivery, signature, retries'
    url: 'https://smklog.com/developers/webhooks'
defaultContentType: application/json
servers:
  subscriber:
    host: '{callbackHost}'
    protocol: https
    title: Your webhook endpoint
    description: 'The server is the receiver’s: the https host of the callback_url given to a payment session. SMKlog is the client that POSTs to it, follows no redirects and waits 8 seconds for a 2xx.'
    variables:
      callbackHost:
        description: 'Host of your callback_url: a public name, never an IP address, a private name or a smklog.com host.'
        examples:
          - agent.example.com
    security:
      - $ref: '#/components/securitySchemes/smklogSignature'
    bindings:
      http: {}
channels:
  paymentSessionEvents:
    address: '{callbackPath}'
    title: Payment-session events
    summary: Every stage a payment session reaches after it was given a callback_url.
    description: 'The path of the callback_url. One channel carries all six events of every session that names this URL; X-Smklog-Event and the body’s event say which one arrived, and session_id says whose.'
    servers:
      - $ref: '#/servers/subscriber'
    parameters:
      callbackPath:
        description: 'The path of your callback_url, as you gave it.'
        examples:
          - '/hooks/smklog'
    messages:
      checkoutStarted:
        $ref: '#/components/messages/checkoutStarted'
      paid:
        $ref: '#/components/messages/paid'
      labelReady:
        $ref: '#/components/messages/labelReady'
      delivered:
        $ref: '#/components/messages/delivered'
      refunded:
        $ref: '#/components/messages/refunded'
      cancelled:
        $ref: '#/components/messages/cancelled'
operations:
  sendPaymentSessionEvent:
    action: send
    channel:
      $ref: '#/channels/paymentSessionEvents'
    title: Send a payment-session event
    summary: 'A payment session reached a new stage (POSTed to your callback_url)'
    description: 'Sent once per stage a session reaches after it was created with a callback_url: checkout_started, paid, label_ready, delivered, refunded, cancelled. The body is a WebhookEvent whose data is the CheckoutStatus of that moment. X-Smklog-Signature carries t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" keyed with the session''s callback_secret>: recompute it over the raw bytes, compare in constant time, and reject a t older than five minutes. Answer any 2xx within 8 seconds; anything else, a redirect, a timeout or a connection error is retried after 1, 5, 15, 60 minutes, 4 and 12 hours (7 attempts in all), with the same id and X-Smklog-Delivery each time, so deduplicate on id. Redirects are never followed. Order is not guaranteed across retries: read data.status rather than counting events.'
    bindings:
      http:
        method: POST
        bindingVersion: '0.3.0'
    messages:
      - $ref: '#/channels/paymentSessionEvents/messages/checkoutStarted'
      - $ref: '#/channels/paymentSessionEvents/messages/paid'
      - $ref: '#/channels/paymentSessionEvents/messages/labelReady'
      - $ref: '#/channels/paymentSessionEvents/messages/delivered'
      - $ref: '#/channels/paymentSessionEvents/messages/refunded'
      - $ref: '#/channels/paymentSessionEvents/messages/cancelled'
components:
  schemas:
    WebhookEvent:
      type: object
      description: 'What SMKlog POSTs to a session''s callback_url each time the session reaches a new stage. The body carries the current CheckoutStatus under data, so a consumer needs no second call.'
      required:
        - id
        - event
        - created_at
        - session_id
        - data
      properties:
        id:
          type: string
          pattern: '^wh_[A-Za-z0-9-]{8,80}$'
          description: 'Delivery id, also sent as X-Smklog-Delivery. The same id on every retry of one event, so consumers can deduplicate.'
        event:
          type: string
          enum:
            - payment_session.checkout_started
            - payment_session.paid
            - payment_session.label_ready
            - payment_session.delivered
            - payment_session.refunded
            - payment_session.cancelled
          description: 'The stage reached, also sent as X-Smklog-Event'
        created_at:
          type: string
          format: date-time
          description: When the stage was observed
        session_id:
          type: string
          description: The session the event belongs to
        data:
          $ref: '#/components/schemas/CheckoutStatus'
    CheckoutStatus:
      type: object
      description: 'The stage of the checkout a session led to, derived from the order record. Never carries names, addresses or emails.'
      required:
        - session_id
        - status
      properties:
        session_id:
          type: string
          description: The session asked about
        status:
          type: string
          enum:
            - awaiting_checkout
            - checkout_started
            - paid
            - label_ready
            - delivered
            - refunded
            - cancelled
          description: 'Stage, in that order; cancelled when cancelPaymentSession ended the session before the human opened checkout'
        created_at:
          type: string
          format: date-time
          description: When the session was made
        expires_at:
          type: string
          format: date-time
          description: When the session stops answering
        amount:
          type: number
          description: 'The amount the session was anchored to, USD'
        currency:
          type: string
          enum:
            - USD
          description: 'ISO currency, USD'
        service:
          type: string
          description: The service the session was anchored to
        quote_reused:
          type: boolean
          description: Whether the session reused a quote_id
        checkout:
          type:
            - object
            - 'null'
          description: 'The checkout the human started, null while awaiting_checkout'
          properties:
            order_id:
              type: string
              description: 'SMKlog order id, the reference for support'
            started_at:
              type: string
              format: date-time
              description: When the checkout was created
            paid:
              type: boolean
            label_ready:
              type: boolean
            refunded:
              type: boolean
            carrier:
              type:
                - string
                - 'null'
              description: 'USPS, UPS, FedEx or DHL'
            service:
              type:
                - string
                - 'null'
              description: The service the human actually chose
            tracking_number:
              type:
                - string
                - 'null'
              description: Present from label_ready on
            tracking_status:
              type:
                - string
                - 'null'
              description: Latest carrier status when known
            estimated_delivery:
              type:
                - string
                - 'null'
              description: ISO date when the carrier gives one
            delivered_at:
              type:
                - string
                - 'null'
              format: date-time
        cancelled_at:
          type:
            - string
            - 'null'
          format: date-time
          description: 'When cancelPaymentSession cancelled the session; null otherwise'
        next:
          type: string
          description: 'What, if anything, the agent should do now'
    DeliveryHeaders:
      type: object
      description: 'The headers on every delivery. The signature is the security scheme smklogSignature; the event and delivery id repeat the body’s event and id.'
      required:
        - X-Smklog-Signature
        - X-Smklog-Event
        - X-Smklog-Delivery
      properties:
        X-Smklog-Signature:
          type: string
          pattern: '^t=[0-9]+,v1=[a-f0-9]{64}$'
          description: 'HMAC-SHA256 over "<t>.<raw body>" with your callback_secret, hex; t is the Unix time of this attempt.'
        X-Smklog-Event:
          type: string
          enum:
            - payment_session.checkout_started
            - payment_session.paid
            - payment_session.label_ready
            - payment_session.delivered
            - payment_session.refunded
            - payment_session.cancelled
          description: Same value as event in the body.
        X-Smklog-Delivery:
          type: string
          pattern: '^wh_[A-Za-z0-9-]{8,80}$'
          description: 'Same value as id in the body; constant across retries.'
    CheckoutStartedEvent:
      description: 'A WebhookEvent for the checkout_started stage: event is payment_session.checkout_started and data.status is checkout_started.'
      allOf:
        - $ref: '#/components/schemas/WebhookEvent'
        - type: object
          properties:
            event:
              const: payment_session.checkout_started
            data:
              type: object
              properties:
                status:
                  const: checkout_started
    PaidEvent:
      description: 'A WebhookEvent for the paid stage: event is payment_session.paid and data.status is paid.'
      allOf:
        - $ref: '#/components/schemas/WebhookEvent'
        - type: object
          properties:
            event:
              const: payment_session.paid
            data:
              type: object
              properties:
                status:
                  const: paid
    LabelReadyEvent:
      description: 'A WebhookEvent for the label_ready stage: event is payment_session.label_ready and data.status is label_ready.'
      allOf:
        - $ref: '#/components/schemas/WebhookEvent'
        - type: object
          properties:
            event:
              const: payment_session.label_ready
            data:
              type: object
              properties:
                status:
                  const: label_ready
    DeliveredEvent:
      description: 'A WebhookEvent for the delivered stage: event is payment_session.delivered and data.status is delivered.'
      allOf:
        - $ref: '#/components/schemas/WebhookEvent'
        - type: object
          properties:
            event:
              const: payment_session.delivered
            data:
              type: object
              properties:
                status:
                  const: delivered
    RefundedEvent:
      description: 'A WebhookEvent for the refunded stage: event is payment_session.refunded and data.status is refunded.'
      allOf:
        - $ref: '#/components/schemas/WebhookEvent'
        - type: object
          properties:
            event:
              const: payment_session.refunded
            data:
              type: object
              properties:
                status:
                  const: refunded
    CancelledEvent:
      description: 'A WebhookEvent for the cancelled stage: event is payment_session.cancelled and data.status is cancelled.'
      allOf:
        - $ref: '#/components/schemas/WebhookEvent'
        - type: object
          properties:
            event:
              const: payment_session.cancelled
            data:
              type: object
              properties:
                status:
                  const: cancelled
  messages:
    checkoutStarted:
      name: payment_session.checkout_started
      title: Payment session checkout started
      summary: 'The human opened the handoff link and a checkout exists; nothing is paid yet.'
      contentType: application/json
      headers:
        $ref: '#/components/schemas/DeliveryHeaders'
      payload:
        $ref: '#/components/schemas/CheckoutStartedEvent'
      correlationId:
        $ref: '#/components/correlationIds/paymentSession'
      examples:
        - name: checkoutStarted
          summary: 'The human opened the handoff link and a checkout exists; nothing is paid yet.'
          headers:
            X-Smklog-Signature: 't=1791817781,v1=a1cf859809d5670c15272c77cf9d6d380990ee91b6691a400bbbaae8c33db57d'
            X-Smklog-Event: payment_session.checkout_started
            X-Smklog-Delivery: wh_7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c10
          payload:
            id: wh_7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c10
            event: payment_session.checkout_started
            created_at: '2026-10-12T15:09:41.000Z'
            session_id: as_3f9c1b2e-7d64-4a8e-9c0f-5b2d1e8a7c33
            data:
              session_id: as_3f9c1b2e-7d64-4a8e-9c0f-5b2d1e8a7c33
              status: checkout_started
              created_at: '2026-10-12T15:04:05.000Z'
              expires_at: '2026-11-11T15:04:05.000Z'
              amount: 38.42
              currency: USD
              service: USPS Ground Advantage
              quote_reused: true
              cancelled_at: null
              checkout:
                order_id: c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f
                started_at: '2026-10-12T15:09:41.000Z'
                paid: false
                label_ready: false
                refunded: false
                carrier: USPS
                service: Ground Advantage
                tracking_number: null
                tracking_status: null
                estimated_delivery: null
                delivered_at: null
              next: A checkout exists but is not paid. Nothing to do but wait for the human.
    paid:
      name: payment_session.paid
      title: Payment session paid
      summary: 'The human paid on smklog.com; label_ready follows once the label is bought.'
      contentType: application/json
      headers:
        $ref: '#/components/schemas/DeliveryHeaders'
      payload:
        $ref: '#/components/schemas/PaidEvent'
      correlationId:
        $ref: '#/components/correlationIds/paymentSession'
      examples:
        - name: paid
          summary: 'The human paid on smklog.com; label_ready follows once the label is bought.'
          headers:
            X-Smklog-Signature: 't=1791817950,v1=e874fd108e1a29ba616067ad9c6deb9fa0efd8c9880c640568364f2bcf6777c6'
            X-Smklog-Event: payment_session.paid
            X-Smklog-Delivery: wh_7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c11
          payload:
            id: wh_7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c11
            event: payment_session.paid
            created_at: '2026-10-12T15:12:30.000Z'
            session_id: as_3f9c1b2e-7d64-4a8e-9c0f-5b2d1e8a7c33
            data:
              session_id: as_3f9c1b2e-7d64-4a8e-9c0f-5b2d1e8a7c33
              status: paid
              created_at: '2026-10-12T15:04:05.000Z'
              expires_at: '2026-11-11T15:04:05.000Z'
              amount: 38.42
              currency: USD
              service: USPS Ground Advantage
              quote_reused: true
              cancelled_at: null
              checkout:
                order_id: c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f
                started_at: '2026-10-12T15:09:41.000Z'
                paid: true
                label_ready: false
                refunded: false
                carrier: USPS
                service: Ground Advantage
                tracking_number: null
                tracking_status: null
                estimated_delivery: null
                delivered_at: null
              next: 'Paid. The checkout page buys the label right after payment; if this stays paid for more than a few minutes, an operator picks it up.'
    labelReady:
      name: payment_session.label_ready
      title: Payment session label ready
      summary: 'The label is bought; data.checkout.tracking_number is set.'
      contentType: application/json
      headers:
        $ref: '#/components/schemas/DeliveryHeaders'
      payload:
        $ref: '#/components/schemas/LabelReadyEvent'
      correlationId:
        $ref: '#/components/correlationIds/paymentSession'
      examples:
        - name: labelReady
          summary: 'The label is bought; data.checkout.tracking_number is set.'
          headers:
            X-Smklog-Signature: 't=1791819072,v1=94c31efd1bca2a08f1bb62ba133c67b7adebc0840ded260243226a211eaa292b'
            X-Smklog-Event: payment_session.label_ready
            X-Smklog-Delivery: wh_7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d
          payload:
            id: wh_7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d
            event: payment_session.label_ready
            created_at: '2026-10-12T15:31:12.000Z'
            session_id: as_3f9c1b2e-7d64-4a8e-9c0f-5b2d1e8a7c33
            data:
              session_id: as_3f9c1b2e-7d64-4a8e-9c0f-5b2d1e8a7c33
              status: label_ready
              created_at: '2026-10-12T15:04:05.000Z'
              expires_at: '2026-11-11T15:04:05.000Z'
              amount: 38.42
              currency: USD
              service: USPS Ground Advantage
              quote_reused: true
              cancelled_at: null
              checkout:
                order_id: c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f
                started_at: '2026-10-12T15:09:41.000Z'
                paid: true
                label_ready: true
                refunded: false
                carrier: USPS
                service: Ground Advantage
                tracking_number: '9400100000000000000000'
                tracking_status: in_transit
                estimated_delivery: '2026-10-16'
                delivered_at: null
              next: Label bought. Pass tracking_number to track_parcel for scan events.
    delivered:
      name: payment_session.delivered
      title: Payment session delivered
      summary: The carrier reported the parcel delivered.
      contentType: application/json
      headers:
        $ref: '#/components/schemas/DeliveryHeaders'
      payload:
        $ref: '#/components/schemas/DeliveredEvent'
      correlationId:
        $ref: '#/components/correlationIds/paymentSession'
      examples:
        - name: delivered
          summary: The carrier reported the parcel delivered.
          headers:
            X-Smklog-Signature: 't=1792093325,v1=a22eeb8303d427ff6d26e650e032c8ac6befc595e2a6e579c2fdf42874562c14'
            X-Smklog-Event: payment_session.delivered
            X-Smklog-Delivery: wh_7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c13
          payload:
            id: wh_7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c13
            event: payment_session.delivered
            created_at: '2026-10-15T19:42:05.000Z'
            session_id: as_3f9c1b2e-7d64-4a8e-9c0f-5b2d1e8a7c33
            data:
              session_id: as_3f9c1b2e-7d64-4a8e-9c0f-5b2d1e8a7c33
              status: delivered
              created_at: '2026-10-12T15:04:05.000Z'
              expires_at: '2026-11-11T15:04:05.000Z'
              amount: 38.42
              currency: USD
              service: USPS Ground Advantage
              quote_reused: true
              cancelled_at: null
              checkout:
                order_id: c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f
                started_at: '2026-10-12T15:09:41.000Z'
                paid: true
                label_ready: true
                refunded: false
                carrier: USPS
                service: Ground Advantage
                tracking_number: '9400100000000000000000'
                tracking_status: delivered
                estimated_delivery: '2026-10-16'
                delivered_at: '2026-10-15T19:42:05.000Z'
              next: Delivered. Nothing further.
    refunded:
      name: payment_session.refunded
      title: Payment session refunded
      summary: 'The payment was refunded or is being refunded; no label from this checkout should be used.'
      contentType: application/json
      headers:
        $ref: '#/components/schemas/DeliveryHeaders'
      payload:
        $ref: '#/components/schemas/RefundedEvent'
      correlationId:
        $ref: '#/components/correlationIds/paymentSession'
      examples:
        - name: refunded
          summary: 'The payment was refunded or is being refunded; no label from this checkout should be used.'
          headers:
            X-Smklog-Signature: 't=1792415100,v1=0ebfb98acde9c3f421fb54baec2be490d7f8636f782fcaf09f91db837d9360dd'
            X-Smklog-Event: payment_session.refunded
            X-Smklog-Delivery: wh_7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c14
          payload:
            id: wh_7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c14
            event: payment_session.refunded
            created_at: '2026-10-19T13:05:00.000Z'
            session_id: as_3f9c1b2e-7d64-4a8e-9c0f-5b2d1e8a7c33
            data:
              session_id: as_3f9c1b2e-7d64-4a8e-9c0f-5b2d1e8a7c33
              status: refunded
              created_at: '2026-10-12T15:04:05.000Z'
              expires_at: '2026-11-11T15:04:05.000Z'
              amount: 38.42
              currency: USD
              service: USPS Ground Advantage
              quote_reused: true
              cancelled_at: null
              checkout:
                order_id: c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f
                started_at: '2026-10-12T15:09:41.000Z'
                paid: true
                label_ready: false
                refunded: true
                carrier: USPS
                service: Ground Advantage
                tracking_number: null
                tracking_status: null
                estimated_delivery: null
                delivered_at: null
              next: Refunded or being refunded. Any label from this checkout should not be used.
    cancelled:
      name: payment_session.cancelled
      title: Payment session cancelled
      summary: The agent cancelled the session before the human opened checkout.
      contentType: application/json
      headers:
        $ref: '#/components/schemas/DeliveryHeaders'
      payload:
        $ref: '#/components/schemas/CancelledEvent'
      correlationId:
        $ref: '#/components/correlationIds/paymentSession'
      examples:
        - name: cancelled
          summary: The agent cancelled the session before the human opened checkout.
          headers:
            X-Smklog-Signature: 't=1791818400,v1=5eaa110633d79140c9b5c75560d4b7afee8c31b78b88a2851a7c11524f048571'
            X-Smklog-Event: payment_session.cancelled
            X-Smklog-Delivery: wh_7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c15
          payload:
            id: wh_7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c15
            event: payment_session.cancelled
            created_at: '2026-10-12T15:20:00.000Z'
            session_id: as_3f9c1b2e-7d64-4a8e-9c0f-5b2d1e8a7c33
            data:
              session_id: as_3f9c1b2e-7d64-4a8e-9c0f-5b2d1e8a7c33
              status: cancelled
              created_at: '2026-10-12T15:04:05Z'
              expires_at: '2026-11-11T15:04:05.000Z'
              amount: 38.42
              currency: USD
              service: USPS Ground Advantage
              quote_reused: true
              cancelled_at: '2026-10-12T15:20:00.000Z'
              checkout: null
              next: 'Cancelled by the agent. The handoff link no longer binds a checkout to this session; create a new session for a new attempt.'
  securitySchemes:
    smklogSignature:
      type: httpApiKey
      name: X-Smklog-Signature
      in: header
      description: 'Not a static key: every delivery is signed. The value is t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" keyed with the session''s callback_secret>. Recompute it over the raw bytes, compare in constant time and reject a t older than five minutes. The examples in this document are signed with the example callback_secret whsec_9f1c2d3e4b5a6978a0b1.'
  correlationIds:
    paymentSession:
      description: 'Every event of one payment session carries the session_id that createPaymentSession, upsertPaymentSession or updatePaymentSession returned.'
      location: '$message.payload#/session_id'
x-provenance:
  method: published
  publisher: 'SMKlog (SMKLOG-2022 LLC)'
  source: 'https://smklog.com/developers/asyncapi.yaml'
  published: '2026-11-07'
