SMKlog Webhooks API

Requests SMKlog makes to your endpoint.

GitHub OpenAPI

Operations 1

POST /your-callback-path A payment session reached a new stage (POSTed to your callback_url) #

Documentation

Specifications

SDKs

Schemas & Data

Other Resources

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/smklog-com:smklog-com-webhooks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

smklog-com-webhooks-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: SMKlog payment-session — receiver contract Webhooks API
  version: 1.5.0
  summary: 'The inbound side of the SMKlog Quote API webhooks: what SMKlog POSTs to a callback_url, as a contract for the endpoint that receives it.'
  description: 'SMKlog POSTs one WebhookEvent to the callback_url a payment session was created with each time the session reaches a new stage (checkout_started, paid, label_ready, delivered, refunded, cancelled), signed with HMAC-SHA256 over "." keyed with the session''s callback_secret and retried on a fixed ladder until the endpoint answers 2xx. This document is that request seen from the receiving server: mount the operation below on any https path, give that URL as callback_url on createPaymentSession, upsertPaymentSession or updatePaymentSession, and verify X-Smklog-Signature before trusting the body. The outbound contract at https://quote-api.smklog.com/openapi.json carries the same event under its webhooks key; the two are generated from one source.'
  termsOfService: https://smklog.com/terms
  contact:
    name: SMKlog
    email: info@smklog.com
    url: https://smklog.com/developers/
  x-publisher: SMKlog (SMKLOG-2022 LLC)
servers:
- url: https://example.com
  description: Your server. The consumer of these events is the server; replace with the host of the callback_url you give a session.
tags:
- name: Webhooks
  description: Requests SMKlog makes to your endpoint.
paths:
  /your-callback-path:
    post:
      operationId: receivePaymentSessionEvent
      tags:
      - Webhooks
      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=,v1=." 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. The path is yours: this operation describes the request SMKlog makes to whatever URL you gave as callback_url.'
      parameters:
      - name: X-Smklog-Signature
        in: header
        required: true
        schema:
          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.
        example: t=1760880000,v1=3b7f2a1c9d8e0f4a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2
      - name: X-Smklog-Event
        in: header
        required: true
        schema:
          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.
      - name: X-Smklog-Delivery
        in: header
        required: true
        schema:
          type: string
          pattern: ^wh_[A-Za-z0-9-]{8,80}$
        description: Same value as id in the body; constant across retries.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEvent'
            example:
              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.
      responses:
        2XX:
          description: 'Acknowledged: the delivery is marked done and not sent again.'
        default:
          description: 'Any other status, a redirect, a timeout (8 seconds) or a connection error: the delivery is retried on the ladder above, then given up after the seventh attempt.'
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
externalDocs:
  description: 'Webhooks guide: setup, events, delivery, signature, retries'
  url: https://smklog.com/developers/webhooks
x-provenance:
  method: published
  publisher: SMKlog (SMKLOG-2022 LLC)
  source: https://smklog.com/developers/webhooks-inbound.openapi.json
  published: '2026-11-07'
x-direction: inbound