SMKlog payment-session webhooks
Version 1.5.0
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.
Channels
Messages
Servers
AsyncAPI Specification
# 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'
Work with this as data
Every AsyncAPI spec 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 asyncapi
4 MCP tools reach this
find_asyncapisBrowse and filter every AsyncAPI spec in the catalog.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.
Call it yourself
curl for this page
curl "https://apis.io/api/v1/asyncapis/smklog-com-webhooks"
curl "https://apis.io/api/v1/asyncapis?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.