Browse the docs

API reference

Webhook endpoints

POSTAdd a webhook endpoint
GETList webhook endpoints
GETGet a webhook endpoint
PATCHUpdate a webhook endpoint
DELETEDelete a webhook endpoint
POSTRoll the signing secret
POSTSend a test event
GETList deliveries to an endpoint
POSTRetry a delivery now

Add a webhook endpoint

POST/v1/webhook-endpoints

The response includes the signing secret, shown only now and when rolled.

Parameters

Idempotency-Keystring · header
Any unique string (a UUID is ideal). Retrying with the same key returns the first result instead of acting twice. Kept for 24 hours.

Request body

urlstringrequired
descriptionstring
eventsarray of enum

Returns · WebhookEndpoint

Show 10 fields

objectstring
iduuidrequired
modeanyrequired
Which environment's events it receives. * live - live * test - test
urlstringrequired
descriptionstringrequired
eventsarray of stringrequired
Empty means every event.
statusenumrequired
* ACTIVE - ACTIVE * DISABLED - DISABLED
ACTIVEDISABLED
disabled_reasonstringrequired
created_attimestamprequired
secretstring
Signing secret. Returned only on create and roll.

Errors: 400, 403, in the standard error format.

Request
curl -X POST https://sandbox.api.scanimart.com/v1/webhook-endpoints \
  -H "Authorization: Bearer $SCANIMART_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://pos.example.com/scanimart/webhooks",
    "description": "Billing server",
    "events": [
      "order.placed"
    ]
  }'

Response · 201
{
  "object": "webhook_endpoint",
  "id": "ORDER-1A2B3C4D5E",
  "mode": null,
  "url": "https://pos.example.com/scanimart/webhooks",
  "description": "Billing server",
  "events": [
    "string"
  ],
  "status": "ACTIVE",
  "disabled_reason": "string",
  "created_at": "2026-10-08T10:15:00+05:30",
  "secret": "string"
}

List webhook endpoints

GET/v1/webhook-endpoints

Returns · WebhookEndpointList

Show 4 fields

objectstring
dataarray of objectrequired
- objectstring
- iduuidrequired
- modeanyrequired
  Which environment's events it receives. * live - live * test - test
- urlstringrequired
- descriptionstringrequired
- eventsarray of stringrequired
  Empty means every event.
- statusenumrequired
  * ACTIVE - ACTIVE * DISABLED - DISABLED
  ACTIVEDISABLED
- disabled_reasonstringrequired
- created_attimestamprequired
- secretstring
  Signing secret. Returned only on create and roll.
has_morebooleanrequired
next_cursorstringnullablerequired
Pass as cursor to get the next page.

Errors: 403, in the standard error format.

Request
curl https://sandbox.api.scanimart.com/v1/webhook-endpoints \
  -H "Authorization: Bearer $SCANIMART_KEY"

Response · 200
{
  "object": "list",
  "data": [
    {
      "object": "webhook_endpoint",
      "id": "ORDER-1A2B3C4D5E",
      "mode": null,
      "url": "https://pos.example.com/scanimart/webhooks",
      "description": "Billing server",
      "events": [
        "string"
      ],
      "status": "ACTIVE",
      "disabled_reason": "string",
      "created_at": "2026-10-08T10:15:00+05:30",
      "secret": "string"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Get a webhook endpoint

GET/v1/webhook-endpoints/{endpoint_id}

Looks up one of the caller's endpoints. Holds no handlers itself: the sub-resource views (roll-secret, test, deliveries) inherit only this, never the detail view's GET/PATCH/DELETE -- otherwise DELETE .../test would delete the endpoint.

Parameters

endpoint_iduuid · pathrequired

Returns · WebhookEndpoint

Show 10 fields

objectstring
iduuidrequired
modeanyrequired
Which environment's events it receives. * live - live * test - test
urlstringrequired
descriptionstringrequired
eventsarray of stringrequired
Empty means every event.
statusenumrequired
* ACTIVE - ACTIVE * DISABLED - DISABLED
ACTIVEDISABLED
disabled_reasonstringrequired
created_attimestamprequired
secretstring
Signing secret. Returned only on create and roll.

Errors: 403, in the standard error format.

Request
curl https://sandbox.api.scanimart.com/v1/webhook-endpoints/3f1c9a2e-6b7d-4c1a-9f0e-2d8b5a7c4e10 \
  -H "Authorization: Bearer $SCANIMART_KEY"

Response · 200
{
  "object": "webhook_endpoint",
  "id": "ORDER-1A2B3C4D5E",
  "mode": null,
  "url": "https://pos.example.com/scanimart/webhooks",
  "description": "Billing server",
  "events": [
    "string"
  ],
  "status": "ACTIVE",
  "disabled_reason": "string",
  "created_at": "2026-10-08T10:15:00+05:30",
  "secret": "string"
}

Update a webhook endpoint

PATCH/v1/webhook-endpoints/{endpoint_id}

Setting status to ACTIVE re-enables an endpoint that was switched off after repeated failures.

Parameters

endpoint_iduuid · pathrequired

Request body

urlstring
descriptionstring
eventsarray of enum
statusenum
* ACTIVE - ACTIVE * DISABLED - DISABLED
ACTIVEDISABLED

Returns · WebhookEndpoint

Show 10 fields

objectstring
iduuidrequired
modeanyrequired
Which environment's events it receives. * live - live * test - test
urlstringrequired
descriptionstringrequired
eventsarray of stringrequired
Empty means every event.
statusenumrequired
* ACTIVE - ACTIVE * DISABLED - DISABLED
ACTIVEDISABLED
disabled_reasonstringrequired
created_attimestamprequired
secretstring
Signing secret. Returned only on create and roll.

Errors: 403, in the standard error format.

Request
curl -X PATCH https://sandbox.api.scanimart.com/v1/webhook-endpoints/3f1c9a2e-6b7d-4c1a-9f0e-2d8b5a7c4e10 \
  -H "Authorization: Bearer $SCANIMART_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://pos.example.com/scanimart/webhooks",
    "description": "Billing server",
    "events": [
      "order.placed"
    ],
    "status": "ACTIVE"
  }'

Response · 200
{
  "object": "webhook_endpoint",
  "id": "ORDER-1A2B3C4D5E",
  "mode": null,
  "url": "https://pos.example.com/scanimart/webhooks",
  "description": "Billing server",
  "events": [
    "string"
  ],
  "status": "ACTIVE",
  "disabled_reason": "string",
  "created_at": "2026-10-08T10:15:00+05:30",
  "secret": "string"
}

Delete a webhook endpoint

DELETE/v1/webhook-endpoints/{endpoint_id}

Parameters

endpoint_iduuid · pathrequired

Errors: 403, in the standard error format.

Request
curl -X DELETE https://sandbox.api.scanimart.com/v1/webhook-endpoints/3f1c9a2e-6b7d-4c1a-9f0e-2d8b5a7c4e10 \
  -H "Authorization: Bearer $SCANIMART_KEY"

Roll the signing secret

POST/v1/webhook-endpoints/{endpoint_id}/roll-secret

The old secret stops working immediately. Update your receiver before calling this.

Parameters

endpoint_iduuid · pathrequired

Returns · WebhookEndpoint

Show 10 fields

objectstring
iduuidrequired
modeanyrequired
Which environment's events it receives. * live - live * test - test
urlstringrequired
descriptionstringrequired
eventsarray of stringrequired
Empty means every event.
statusenumrequired
* ACTIVE - ACTIVE * DISABLED - DISABLED
ACTIVEDISABLED
disabled_reasonstringrequired
created_attimestamprequired
secretstring
Signing secret. Returned only on create and roll.

Errors: 403, in the standard error format.

Request
curl -X POST https://sandbox.api.scanimart.com/v1/webhook-endpoints/3f1c9a2e-6b7d-4c1a-9f0e-2d8b5a7c4e10/roll-secret \
  -H "Authorization: Bearer $SCANIMART_KEY"

Response · 200
{
  "object": "webhook_endpoint",
  "id": "ORDER-1A2B3C4D5E",
  "mode": null,
  "url": "https://pos.example.com/scanimart/webhooks",
  "description": "Billing server",
  "events": [
    "string"
  ],
  "status": "ACTIVE",
  "disabled_reason": "string",
  "created_at": "2026-10-08T10:15:00+05:30",
  "secret": "string"
}

Send a test event

POST/v1/webhook-endpoints/{endpoint_id}/test

Sends one event to this endpoint now and reports how it answered. With bad_signature: true the signature is deliberately wrong -- a correct receiver answers 4xx (this is on the go-live checklist).

Parameters

endpoint_iduuid · pathrequired

Request body

typeany
bad_signatureboolean
Send with a deliberately wrong signature. Your endpoint should answer 4xx.

Returns · WebhookDelivery

Show 11 fields

objectstring
idintegerrequired
event_idstringrequired
event_typestringrequired
statusenumrequired
* PENDING - PENDING * SUCCEEDED - SUCCEEDED * DEAD - DEAD
PENDINGSUCCEEDEDDEAD
attemptsintegerrequired
next_attempt_attimestampnullablerequired
last_status_codeintegernullablerequired
last_errorstringrequired
created_attimestamprequired
succeeded_attimestampnullablerequired

Errors: 403, in the standard error format.

Request
curl -X POST https://sandbox.api.scanimart.com/v1/webhook-endpoints/3f1c9a2e-6b7d-4c1a-9f0e-2d8b5a7c4e10/test \
  -H "Authorization: Bearer $SCANIMART_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ping",
    "bad_signature": false
  }'

Response · 200
{
  "object": "webhook_delivery",
  "id": 1,
  "event_id": "evt_8f14e45fceea167a5a36dedd4bea2543",
  "event_type": "string",
  "status": "PENDING",
  "attempts": 1,
  "next_attempt_at": "2026-10-08T10:15:00+05:30",
  "last_status_code": 1,
  "last_error": "string",
  "created_at": "2026-10-08T10:15:00+05:30",
  "succeeded_at": "2026-10-08T10:15:00+05:30"
}

List deliveries to an endpoint

GET/v1/webhook-endpoints/{endpoint_id}/deliveries

Parameters

endpoint_iduuid · pathrequired
cursorstring · query
Opaque cursor from a previous page's next_cursor.
limitinteger · query
Page size, 1–100. Default 50.
statusenum · query
DEADPENDINGSUCCEEDED

Returns · WebhookDeliveryList

Show 4 fields

objectstring
dataarray of objectrequired
- objectstring
- idintegerrequired
- event_idstringrequired
- event_typestringrequired
- statusenumrequired
  * PENDING - PENDING * SUCCEEDED - SUCCEEDED * DEAD - DEAD
  PENDINGSUCCEEDEDDEAD
- attemptsintegerrequired
- next_attempt_attimestampnullablerequired
- last_status_codeintegernullablerequired
- last_errorstringrequired
- created_attimestamprequired
- succeeded_attimestampnullablerequired
has_morebooleanrequired
next_cursorstringnullablerequired
Pass as cursor to get the next page.

Errors: 403, in the standard error format.

Request
curl https://sandbox.api.scanimart.com/v1/webhook-endpoints/3f1c9a2e-6b7d-4c1a-9f0e-2d8b5a7c4e10/deliveries \
  -H "Authorization: Bearer $SCANIMART_KEY"

Response · 200
{
  "object": "list",
  "data": [
    {
      "object": "webhook_delivery",
      "id": 1,
      "event_id": "evt_8f14e45fceea167a5a36dedd4bea2543",
      "event_type": "string",
      "status": "PENDING",
      "attempts": 1,
      "next_attempt_at": "2026-10-08T10:15:00+05:30",
      "last_status_code": 1,
      "last_error": "string",
      "created_at": "2026-10-08T10:15:00+05:30",
      "succeeded_at": "2026-10-08T10:15:00+05:30"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Retry a delivery now

POST/v1/webhook-deliveries/{delivery_id}/retry

Re-sends a failed or given-up delivery straight away.

Parameters

delivery_idinteger · pathrequired

Returns · WebhookDelivery

Show 11 fields

objectstring
idintegerrequired
event_idstringrequired
event_typestringrequired
statusenumrequired
* PENDING - PENDING * SUCCEEDED - SUCCEEDED * DEAD - DEAD
PENDINGSUCCEEDEDDEAD
attemptsintegerrequired
next_attempt_attimestampnullablerequired
last_status_codeintegernullablerequired
last_errorstringrequired
created_attimestamprequired
succeeded_attimestampnullablerequired

Errors: 403, in the standard error format.

Request
curl -X POST https://sandbox.api.scanimart.com/v1/webhook-deliveries/88/retry \
  -H "Authorization: Bearer $SCANIMART_KEY"

Response · 200
{
  "object": "webhook_delivery",
  "id": 1,
  "event_id": "evt_8f14e45fceea167a5a36dedd4bea2543",
  "event_type": "string",
  "status": "PENDING",
  "attempts": 1,
  "next_attempt_at": "2026-10-08T10:15:00+05:30",
  "last_status_code": 1,
  "last_error": "string",
  "created_at": "2026-10-08T10:15:00+05:30",
  "succeeded_at": "2026-10-08T10:15:00+05:30"
}