API section

Webhooks

Account webhooks: register alerts, printing and receipt outcomes — to your server, signed with HMAC-SHA256, with retries and a delivery log.

GET	`/api/v1/webhooks`	Account webhooks
POST	`/api/v1/webhooks`	Add a webhook
POST	`/api/v1/webhooks/{id}/test`	Test a webhook
GET	`/api/v1/webhooks/{id}/deliveries`	Webhook delivery log
DELETE	`/api/v1/webhooks/{id}`	Delete a webhook

Account webhooks#

GET/api/v1/webhooks

Addresses the cloud sends account register events to, and how the last delivery went

Response 200 application/json

Array · WebhookView

idinteger int64
urlstring
eventsarray of string
secretstring
createdAtstring date-time
lastAtstring date-time
lastStatusinteger int32
lastErrorstring
failuresinteger int32

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'https://cloud.hw-connector.ru/api/v1/webhooks' \
  -H 'X-Api-Key: hwk_…'

Add a webhook#

POST/api/v1/webhooks

Events: alert.opened, alert.closed (register alerts), device.online, device.offline (a register connected to the cloud; disconnected and did not come back within 10 s), operation.failed (a failed operation on a register), print_job.done, print_job.failed, print_job.cancelled, print_job.expired, print_job.unknown (cloud printing outcomes), receipt.done, receipt.failed, receipt.unknown, receipt.expired (receipt outcomes); the mask print_job.* and * — all. A letter is POST JSON {event, at, …} signed with X-HW-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<body>")>, the letter id — X-HW-Delivery; a 2xx answer means delivered, otherwise up to 10 attempts over ~8 h. The secret is in the response, once. An address in a local network — 400; at most 5 webhooks per account

Request body application/json required

Fields · WebhookRequest

urlstringrequired
from 0
to 500
eventsarray of string

JSON

{
  "url": "string",
  "events": [
    "string"
  ]
}

Response 200 application/json

Fields · WebhookView

idinteger int64
urlstring
eventsarray of string
secretstring
createdAtstring date-time
lastAtstring date-time
lastStatusinteger int32
lastErrorstring
failuresinteger int32

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X POST 'https://cloud.hw-connector.ru/api/v1/webhooks' \
  -H 'X-Api-Key: hwk_…' \
  -H 'Content-Type: application/json' \
  --data '{"url":"string","events":["string"]}'

Test a webhook#

POST/api/v1/webhooks/{id}/test

Send a ping letter {event: "ping"} — check the address and the signature; the outcome is in the delivery log

Parameters

Name	In	Type	Description
`id`required	path	integer int64

Response 200 application/json

Fields · DeliveryView

idinteger int64
eventstring
attemptsinteger int32
statestring
lastStatusinteger int32
lastErrorstring
createdAtstring date-time
nextAtstring date-time
payloadobject

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X POST 'https://cloud.hw-connector.ru/api/v1/webhooks/42/test' \
  -H 'X-Api-Key: hwk_…'

Webhook delivery log#

GET/api/v1/webhooks/{id}/deliveries

Recent letters, newest first: event, attempts, state (DELIVERED, RETRYING, FAILED), response status, error and body

Parameters

Name	In	Type	Description
`id`required	path	integer int64
`limit`	query	integer int32

Response 200 application/json

Array · DeliveryView

idinteger int64
eventstring
attemptsinteger int32
statestring
lastStatusinteger int32
lastErrorstring
createdAtstring date-time
nextAtstring date-time
payloadobject

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'https://cloud.hw-connector.ru/api/v1/webhooks/42/deliveries' \
  -H 'X-Api-Key: hwk_…'

Delete a webhook#

DELETE/api/v1/webhooks/{id}

Letters not yet delivered are no longer sent

Parameters

Name	In	Type	Description
`id`required	path	integer int64

Response 200

No body.

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X DELETE 'https://cloud.hw-connector.ru/api/v1/webhooks/42' \
  -H 'X-Api-Key: hwk_…'