Webhooks

Signed notifications of changes to your HTTPS addresses and a feed of the same events. A notification is never proof of fiscalization.

11 operations

Event feed

get/v1/events

Scopewebhooks:read

The same events that webhooks push, oldest first, for the last 30 days. Keep `nextCursor` and send it as `after` next time; when nothing new happened, the same cursor comes back.

GET/v1/events

curl -X GET "https://api.bokapos.rs/v1/events?after=1041&types=fiscal-document.fiscalized%2Cfiscal-document.outcome-unknown&limit=100" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

200OK

{
  "items": [
    {
      "id": "21c0738c-e29c-480f-92a9-fb88a99dc514",
      "type": "fiscal-document.fiscalized",
      "timestamp": "2026-11-02T09:14:03.512+00:00",
      "environment": "sandbox",
      "data": {
        "fiscalDocumentId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761",
        "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
        "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
        "status": "FISCALIZED",
        "invoiceType": "NORMAL",
        "transactionType": "SALE",
        "clientReference": "ORDER-4127",
        "idempotencyKey": "order-4127-sale-1",
        "pfrInvoiceNumber": "JWX4K9PL-JWX4K9PL-1042",
        "pfrSdcTime": "2026-11-02T10:14:03.1+01:00",
        "totalAmount": 8990,
        "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
        "failureCode": null
      }
    }
  ],
  "nextCursor": "1042",
  "hasMore": false
}

Keep nextCursor and send it as after next time. While hasMore is true, ask for the next page right away.

Contract notes (OpenAPI)

Keep `nextCursor` and send it as `after` on the next call; with nothing new the same cursor comes back. Events appear a moment after they commit and stay for 30 days. Test events never appear. Scoped to the caller's environment like every other read.

Parameters

listEvents: Parameters
Field	Description
`after`optionalIn: queryType: string	Opaque cursor from a previous page. pattern ^[0-9]{1,19}$
`types`optionalIn: queryType: string	Comma-separated event types to include.
`limit`optionalIn: queryType: integer	>= 1<= 200default 100

Responses

listEvents: Responses
200OK	Page of events`WebhookEventPage`
422Unprocessable Content	The command violates a Boka or fiscal rule`ErrorCode`

Response: WebhookEventPage

Field descriptions come from the OpenAPI contract; field names and values are identical in both languages.

listEvents: Response
Field	Description
`items`requiredType: array<WebhookEvent>
`id`requiredType: uuid
`type`requiredType: string	A WebhookEventType, or webhook-endpoint.test on a pushed test event.
`timestamp`requiredType: date-time	When the change happened, not when it was delivered.
`environment`requiredType: string	Values`sandboxproduction`
`data`requiredType: WebhookFiscalDocumentData \| WebhookReceiptDeliveryData \| WebhookSecurityElementData \| WebhookLicenseData \| WebhookTestData	One of: WebhookFiscalDocumentData \| WebhookReceiptDeliveryData \| WebhookSecurityElementData \| WebhookLicenseData \| WebhookTestData
WebhookFiscalDocumentData
`fiscalDocumentId`requiredType: uuid
`taxpayerId`requiredType: uuid
`businessPremiseId`requiredType: uuid
`status`requiredType: string	Values`FISCALIZEDOUTCOME_UNKNOWN`
`invoiceType`requiredType: InvoiceType	Values`NORMALPROFORMACOPYTRAININGADVANCE`
`transactionType`requiredType: TransactionType	Values`SALEREFUND`
`clientReference`requiredType: string \| null (nullable)
`idempotencyKey`requiredType: string
`pfrInvoiceNumber`requiredType: string \| null (nullable)
`pfrSdcTime`requiredType: date-time \| null (nullable)
`totalAmount`requiredType: number \| null (nullable)
`verificationUrl`requiredType: uri \| null (nullable)
`failureCode`requiredType: string \| null (nullable)
WebhookReceiptDeliveryData
`receiptDeliveryId`requiredType: uuid
`fiscalDocumentId`requiredType: uuid
`taxpayerId`requiredType: uuid
`businessPremiseId`requiredType: uuid
`channel`requiredType: const "EMAIL"
`status`requiredType: string	Values`DELIVEREDFAILED`
`attempts`requiredType: integer	>= 1
`deliveredAt`requiredType: date-time \| null (nullable)
`failureCode`requiredType: string \| null (nullable)
WebhookSecurityElementData
`securityElementId`requiredType: uuid
`taxpayerId`requiredType: uuid
`businessPremiseId`requiredType: uuid
`jid`requiredType: string
`status`requiredType: string	Values`activesuspendedretired`
`certificateNotAfter`requiredType: date-time
`expiryStatus`optionalType: string	Only on security-element.expiring. Values`warningcritical`
`daysRemaining`optionalType: integer	Whole days until the certificate expires; only on security-element.expiring. >= 0
WebhookLicenseData
`status`requiredType: string	Values`activesuspended`
`startsOn`requiredType: date
`endsOn`requiredType: date \| null (nullable)
`advanceModuleEnabled`requiredType: boolean
`emailModuleEnabled`requiredType: boolean
WebhookTestData
`webhookEndpointId`requiredType: uuid
`nextCursor`requiredType: string \| null (nullable)	Send as after next time; null only before the first event.
`hasMore`requiredType: boolean

Read an event

get/v1/events/{eventId}

Scopewebhooks:read

One event from the last 30 days, the same shape as the webhook body. Test events cannot be read here.

GET/v1/events/{eventId}

curl -X GET "https://api.bokapos.rs/v1/events/21c0738c-e29c-480f-92a9-fb88a99dc514" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

{
  "id": "21c0738c-e29c-480f-92a9-fb88a99dc514",
  "type": "fiscal-document.fiscalized",
  "timestamp": "2026-11-02T09:14:03.512+00:00",
  "environment": "sandbox",
  "data": {
    "fiscalDocumentId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761",
    "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
    "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
    "status": "FISCALIZED",
    "invoiceType": "NORMAL",
    "transactionType": "SALE",
    "clientReference": "ORDER-4127",
    "idempotencyKey": "order-4127-sale-1",
    "pfrInvoiceNumber": "JWX4K9PL-JWX4K9PL-1042",
    "pfrSdcTime": "2026-11-02T10:14:03.1+01:00",
    "totalAmount": 8990,
    "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
    "failureCode": null
  }
}

Parameters

getEvent: Parameters
Field	Description
`eventId`requiredIn: pathType: uuid

Responses

getEvent: Responses
200OK	Event`WebhookEvent`
404Not Found	Resource does not exist within the authenticated tenant scope`ErrorCode`

Response: WebhookEvent

Field descriptions come from the OpenAPI contract; field names and values are identical in both languages.

getEvent: Response
Field	Description
`id`requiredType: uuid
`type`requiredType: string	A WebhookEventType, or webhook-endpoint.test on a pushed test event.
`timestamp`requiredType: date-time	When the change happened, not when it was delivered.
`environment`requiredType: string	Values`sandboxproduction`
`data`requiredType: WebhookFiscalDocumentData \| WebhookReceiptDeliveryData \| WebhookSecurityElementData \| WebhookLicenseData \| WebhookTestData	One of: WebhookFiscalDocumentData \| WebhookReceiptDeliveryData \| WebhookSecurityElementData \| WebhookLicenseData \| WebhookTestData
WebhookFiscalDocumentData
`fiscalDocumentId`requiredType: uuid
`taxpayerId`requiredType: uuid
`businessPremiseId`requiredType: uuid
`status`requiredType: string	Values`FISCALIZEDOUTCOME_UNKNOWN`
`invoiceType`requiredType: InvoiceType	Values`NORMALPROFORMACOPYTRAININGADVANCE`
`transactionType`requiredType: TransactionType	Values`SALEREFUND`
`clientReference`requiredType: string \| null (nullable)
`idempotencyKey`requiredType: string
`pfrInvoiceNumber`requiredType: string \| null (nullable)
`pfrSdcTime`requiredType: date-time \| null (nullable)
`totalAmount`requiredType: number \| null (nullable)
`verificationUrl`requiredType: uri \| null (nullable)
`failureCode`requiredType: string \| null (nullable)
WebhookReceiptDeliveryData
`receiptDeliveryId`requiredType: uuid
`fiscalDocumentId`requiredType: uuid
`taxpayerId`requiredType: uuid
`businessPremiseId`requiredType: uuid
`channel`requiredType: const "EMAIL"
`status`requiredType: string	Values`DELIVEREDFAILED`
`attempts`requiredType: integer	>= 1
`deliveredAt`requiredType: date-time \| null (nullable)
`failureCode`requiredType: string \| null (nullable)
WebhookSecurityElementData
`securityElementId`requiredType: uuid
`taxpayerId`requiredType: uuid
`businessPremiseId`requiredType: uuid
`jid`requiredType: string
`status`requiredType: string	Values`activesuspendedretired`
`certificateNotAfter`requiredType: date-time
`expiryStatus`optionalType: string	Only on security-element.expiring. Values`warningcritical`
`daysRemaining`optionalType: integer	Whole days until the certificate expires; only on security-element.expiring. >= 0
WebhookLicenseData
`status`requiredType: string	Values`activesuspended`
`startsOn`requiredType: date
`endsOn`requiredType: date \| null (nullable)
`advanceModuleEnabled`requiredType: boolean
`emailModuleEnabled`requiredType: boolean
WebhookTestData
`webhookEndpointId`requiredType: uuid

List webhook endpoints

get/v1/webhook-endpoints

Scopewebhooks:read

The endpoints of your credential's environment, with their state (enabled or disabled and why), the last success and failure, and who added them. Removed endpoints are not listed.

GET/v1/webhook-endpoints

curl -X GET "https://api.bokapos.rs/v1/webhook-endpoints" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

200OK

{
  "items": [
    {
      "id": "287978af-8d23-4e51-8c51-59d60c5fb9c3",
      "environment": "sandbox",
      "url": "https://shop.example.com/bokapos/webhooks",
      "description": "Web shop: status porudžbina",
      "eventTypes": [
        "fiscal-document.fiscalized",
        "fiscal-document.outcome-unknown",
        "receipt-delivery.failed"
      ],
      "enabled": true,
      "status": "enabled",
      "disabledReason": null,
      "failingSince": null,
      "lastSuccessAt": "2026-11-02T09:14:04.120Z",
      "lastFailureAt": null,
      "createdBy": {
        "kind": "api-credential",
        "name": null
      },
      "createdAt": "2026-11-02T09:00:00.000Z",
      "updatedAt": "2026-11-02T09:14:04.120Z"
    }
  ]
}

Contract notes (OpenAPI)

A machine credential sees the endpoints of its own environment. A customer Owner or Administrator sees both environments unless the organization hides its sandbox data. Deleted endpoints are not listed.

Responses

listWebhookEndpoints: Responses
200OK	Webhook endpoints`WebhookEndpointList`

Response: WebhookEndpointList

Field descriptions come from the OpenAPI contract; field names and values are identical in both languages.

listWebhookEndpoints: Response
Field	Description
`items`requiredType: array<WebhookEndpoint>
`id`requiredType: uuid
`environment`requiredType: string	Values`sandboxproduction`
`url`requiredType: uri	max 2048
`description`requiredType: string \| null (nullable)	max 200
`eventTypes`requiredType: array<WebhookEventType>	Values`fiscal-document.fiscalizedfiscal-document.outcome-unknownreceipt-delivery.deliveredreceipt-delivery.failedsecurity-element.activatedsecurity-element.suspendedsecurity-element.retiredsecurity-element.expiringlicense.updated`min 1 items
`enabled`requiredType: boolean
`status`requiredType: string	Values`enableddisabled`
`disabledReason`requiredType: string \| null (nullable)	failing means 72 hours of failed deliveries without a single success; revoked means the API key or AI connection that registered the endpoint was revoked, or the AI connection lost its webhooks permission. `PUT` with `enabled: true` switches it back on. Values`manualfailingrevoked`
`failingSince`requiredType: date-time \| null (nullable)
`lastSuccessAt`requiredType: date-time \| null (nullable)
`lastFailureAt`requiredType: date-time \| null (nullable)
`createdBy`requiredType: object	Who registered the endpoint. The name is returned to Owners and Administrators only, never to a machine credential.
`kind`requiredType: string	Values`personapi-credentialai-connectionunknown`
`name`requiredType: string \| null (nullable)	max 200
`createdAt`requiredType: date-time
`updatedAt`requiredType: date-time

Add a webhook endpoint

post/v1/webhook-endpoints

Scopewebhooks:write

Registers a public HTTPS address and the event types it receives. A credential always registers in its own environment, so it may omit `environment`. The same `url` exists only once per environment (`409` returns the existing endpoint), and an organization has at most ten endpoints per environment.

POST/v1/webhook-endpoints

curl -X POST "https://api.bokapos.rs/v1/webhook-endpoints" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://shop.example.com/bokapos/webhooks",
  "description": "Web shop: status porudžbina",
  "eventTypes": [
    "fiscal-document.fiscalized",
    "fiscal-document.outcome-unknown",
    "receipt-delivery.failed"
  ]
}'

{
  "id": "287978af-8d23-4e51-8c51-59d60c5fb9c3",
  "environment": "sandbox",
  "url": "https://shop.example.com/bokapos/webhooks",
  "description": "Web shop: status porudžbina",
  "eventTypes": [
    "fiscal-document.fiscalized",
    "fiscal-document.outcome-unknown",
    "receipt-delivery.failed"
  ],
  "enabled": true,
  "status": "enabled",
  "disabledReason": null,
  "failingSince": null,
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "createdBy": {
    "kind": "api-credential",
    "name": null
  },
  "createdAt": "2026-11-02T09:00:00.000Z",
  "updatedAt": "2026-11-02T09:00:00.000Z"
}

The credential sends no environment: the endpoint always belongs to its own environment. createdBy.name is null because only people in the portal see the author's name.

Contract notes (OpenAPI)

The URL must be absolute https without user information or a fragment and must resolve to a public address; it is checked again at every connection. A machine credential registers in its own environment and may omit `environment`; a human must name it. One live endpoint per URL and environment: registering the same URL again answers 409 with the existing `webhookEndpointId`. At most ten endpoints per organization and environment. Free in the base licence.

Request bodyapplication/json

createWebhookEndpoint: Request body
Field	Description
`url`requiredType: uri	max 2048
`description`optionalType: string \| null (nullable)	max 200
`eventTypes`requiredType: array<WebhookEventType>	Values`fiscal-document.fiscalizedfiscal-document.outcome-unknownreceipt-delivery.deliveredreceipt-delivery.failedsecurity-element.activatedsecurity-element.suspendedsecurity-element.retiredsecurity-element.expiringlicense.updated`min 1 items
`environment`optionalType: string \| null (nullable)	Required for humans; a machine credential may omit it and always uses its own environment. Values`sandboxproduction`

Responses

createWebhookEndpoint: Responses
201Created	Endpoint created`WebhookEndpoint`
409Conflict	The URL is already registered in this environment, or the endpoint limit is reached`WebhookEndpointConflict`
422Unprocessable Content	The command violates a Boka or fiscal rule`ErrorCode`

Response: WebhookEndpoint

Field descriptions come from the OpenAPI contract; field names and values are identical in both languages.

createWebhookEndpoint: Response
Field	Description
`id`requiredType: uuid
`environment`requiredType: string	Values`sandboxproduction`
`url`requiredType: uri	max 2048
`description`requiredType: string \| null (nullable)	max 200
`eventTypes`requiredType: array<WebhookEventType>	Values`fiscal-document.fiscalizedfiscal-document.outcome-unknownreceipt-delivery.deliveredreceipt-delivery.failedsecurity-element.activatedsecurity-element.suspendedsecurity-element.retiredsecurity-element.expiringlicense.updated`min 1 items
`enabled`requiredType: boolean
`status`requiredType: string	Values`enableddisabled`
`disabledReason`requiredType: string \| null (nullable)	failing means 72 hours of failed deliveries without a single success; revoked means the API key or AI connection that registered the endpoint was revoked, or the AI connection lost its webhooks permission. `PUT` with `enabled: true` switches it back on. Values`manualfailingrevoked`
`failingSince`requiredType: date-time \| null (nullable)
`lastSuccessAt`requiredType: date-time \| null (nullable)
`lastFailureAt`requiredType: date-time \| null (nullable)
`createdBy`requiredType: object	Who registered the endpoint. The name is returned to Owners and Administrators only, never to a machine credential.
`kind`requiredType: string	Values`personapi-credentialai-connectionunknown`
`name`requiredType: string \| null (nullable)	max 200
`createdAt`requiredType: date-time
`updatedAt`requiredType: date-time

Read a webhook endpoint

get/v1/webhook-endpoints/{webhookEndpointId}

Scopewebhooks:read

One endpoint by identifier, the same fields as the list.

GET/v1/webhook-endpoints/{webhookEndpointId}

curl -X GET "https://api.bokapos.rs/v1/webhook-endpoints/287978af-8d23-4e51-8c51-59d60c5fb9c3" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

200OK

{
  "id": "287978af-8d23-4e51-8c51-59d60c5fb9c3",
  "environment": "sandbox",
  "url": "https://shop.example.com/bokapos/webhooks",
  "description": "Web shop: status porudžbina",
  "eventTypes": [
    "fiscal-document.fiscalized",
    "fiscal-document.outcome-unknown",
    "receipt-delivery.failed"
  ],
  "enabled": true,
  "status": "enabled",
  "disabledReason": null,
  "failingSince": null,
  "lastSuccessAt": "2026-11-02T09:14:04.120Z",
  "lastFailureAt": null,
  "createdBy": {
    "kind": "api-credential",
    "name": null
  },
  "createdAt": "2026-11-02T09:00:00.000Z",
  "updatedAt": "2026-11-02T09:14:04.120Z"
}

Parameters

getWebhookEndpoint: Parameters
Field	Description
`webhookEndpointId`requiredIn: pathType: uuid

Responses

getWebhookEndpoint: Responses
200OK	Webhook endpoint`WebhookEndpoint`
404Not Found	Resource does not exist within the authenticated tenant scope`ErrorCode`

Response: WebhookEndpoint

Field descriptions come from the OpenAPI contract; field names and values are identical in both languages.

getWebhookEndpoint: Response
Field	Description
`id`requiredType: uuid
`environment`requiredType: string	Values`sandboxproduction`
`url`requiredType: uri	max 2048
`description`requiredType: string \| null (nullable)	max 200
`eventTypes`requiredType: array<WebhookEventType>	Values`fiscal-document.fiscalizedfiscal-document.outcome-unknownreceipt-delivery.deliveredreceipt-delivery.failedsecurity-element.activatedsecurity-element.suspendedsecurity-element.retiredsecurity-element.expiringlicense.updated`min 1 items
`enabled`requiredType: boolean
`status`requiredType: string	Values`enableddisabled`
`disabledReason`requiredType: string \| null (nullable)	failing means 72 hours of failed deliveries without a single success; revoked means the API key or AI connection that registered the endpoint was revoked, or the AI connection lost its webhooks permission. `PUT` with `enabled: true` switches it back on. Values`manualfailingrevoked`
`failingSince`requiredType: date-time \| null (nullable)
`lastSuccessAt`requiredType: date-time \| null (nullable)
`lastFailureAt`requiredType: date-time \| null (nullable)
`createdBy`requiredType: object	Who registered the endpoint. The name is returned to Owners and Administrators only, never to a machine credential.
`kind`requiredType: string	Values`personapi-credentialai-connectionunknown`
`name`requiredType: string \| null (nullable)	max 200
`createdAt`requiredType: date-time
`updatedAt`requiredType: date-time

Update a webhook endpoint

put/v1/webhook-endpoints/{webhookEndpointId}

Scopewebhooks:write

Replaces `url`, `description`, `eventTypes` and `enabled` at once; the environment never changes. With `enabled: true` it switches back on an endpoint that was disabled by hand, after 72 hours of failed deliveries or by revoking the credential that added it. When the record changed meanwhile, `409 WEBHOOK_ENDPOINT_CHANGED` asks you to read it again.

PUT/v1/webhook-endpoints/{webhookEndpointId}

curl -X PUT "https://api.bokapos.rs/v1/webhook-endpoints/287978af-8d23-4e51-8c51-59d60c5fb9c3" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://shop.example.com/bokapos/webhooks",
  "description": "Web shop: status porudžbina i e-pošte",
  "eventTypes": [
    "fiscal-document.fiscalized",
    "fiscal-document.outcome-unknown",
    "receipt-delivery.delivered",
    "receipt-delivery.failed"
  ],
  "enabled": true
}'

{
  "id": "287978af-8d23-4e51-8c51-59d60c5fb9c3",
  "environment": "sandbox",
  "url": "https://shop.example.com/bokapos/webhooks",
  "description": "Web shop: status porudžbina i e-pošte",
  "eventTypes": [
    "fiscal-document.fiscalized",
    "fiscal-document.outcome-unknown",
    "receipt-delivery.delivered",
    "receipt-delivery.failed"
  ],
  "enabled": true,
  "status": "enabled",
  "disabledReason": null,
  "failingSince": null,
  "lastSuccessAt": "2026-11-02T09:14:04.120Z",
  "lastFailureAt": null,
  "createdBy": {
    "kind": "api-credential",
    "name": null
  },
  "createdAt": "2026-11-02T09:00:00.000Z",
  "updatedAt": "2026-11-02T11:30:00.000Z"
}

Contract notes (OpenAPI)

`enabled: true` re-enables an endpoint that was switched off by hand or after 72 hours of failed deliveries; delivery resumes with new events. The environment never changes.

Parameters

putWebhookEndpoint: Parameters
Field	Description
`webhookEndpointId`requiredIn: pathType: uuid

Request bodyapplication/json

putWebhookEndpoint: Request body
Field	Description
`url`requiredType: uri	max 2048
`description`optionalType: string \| null (nullable)	max 200
`eventTypes`requiredType: array<WebhookEventType>	Values`fiscal-document.fiscalizedfiscal-document.outcome-unknownreceipt-delivery.deliveredreceipt-delivery.failedsecurity-element.activatedsecurity-element.suspendedsecurity-element.retiredsecurity-element.expiringlicense.updated`min 1 items
`enabled`requiredType: boolean

Responses

putWebhookEndpoint: Responses
200OK	Updated endpoint`WebhookEndpoint`
404Not Found	Resource does not exist within the authenticated tenant scope`ErrorCode`
409Conflict	`WEBHOOK_ENDPOINT_URL_EXISTS` when another endpoint of this environment already uses the URL; `WEBHOOK_ENDPOINT_CHANGED` when the endpoint changed meanwhile (a delivery result is recorded on it after every attempt): read it again and repeat the change.`Conflict`
422Unprocessable Content	The command violates a Boka or fiscal rule`ErrorCode`

Response: WebhookEndpoint

Field descriptions come from the OpenAPI contract; field names and values are identical in both languages.

putWebhookEndpoint: Response
Field	Description
`id`requiredType: uuid
`environment`requiredType: string	Values`sandboxproduction`
`url`requiredType: uri	max 2048
`description`requiredType: string \| null (nullable)	max 200
`eventTypes`requiredType: array<WebhookEventType>	Values`fiscal-document.fiscalizedfiscal-document.outcome-unknownreceipt-delivery.deliveredreceipt-delivery.failedsecurity-element.activatedsecurity-element.suspendedsecurity-element.retiredsecurity-element.expiringlicense.updated`min 1 items
`enabled`requiredType: boolean
`status`requiredType: string	Values`enableddisabled`
`disabledReason`requiredType: string \| null (nullable)	failing means 72 hours of failed deliveries without a single success; revoked means the API key or AI connection that registered the endpoint was revoked, or the AI connection lost its webhooks permission. `PUT` with `enabled: true` switches it back on. Values`manualfailingrevoked`
`failingSince`requiredType: date-time \| null (nullable)
`lastSuccessAt`requiredType: date-time \| null (nullable)
`lastFailureAt`requiredType: date-time \| null (nullable)
`createdBy`requiredType: object	Who registered the endpoint. The name is returned to Owners and Administrators only, never to a machine credential.
`kind`requiredType: string	Values`personapi-credentialai-connectionunknown`
`name`requiredType: string \| null (nullable)	max 200
`createdAt`requiredType: date-time
`updatedAt`requiredType: date-time

Remove a webhook endpoint

delete/v1/webhook-endpoints/{webhookEndpointId}

Scopewebhooks:write

Removes the endpoint and cancels its pending deliveries. The answer is `204` with no body; `409 WEBHOOK_ENDPOINT_CHANGED` means read the endpoint and repeat the removal.

DELETE/v1/webhook-endpoints/{webhookEndpointId}

curl -X DELETE "https://api.bokapos.rs/v1/webhook-endpoints/287978af-8d23-4e51-8c51-59d60c5fb9c3" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

204No Content

Empty body. Pending deliveries are cancelled.

Contract notes (OpenAPI)

Pending deliveries are cancelled; the delivery history is kept.

Parameters

deleteWebhookEndpoint: Parameters
Field	Description
`webhookEndpointId`requiredIn: pathType: uuid

Responses

deleteWebhookEndpoint: Responses
204No Content	Endpoint removed
404Not Found	Resource does not exist within the authenticated tenant scope`ErrorCode`
409Conflict	`WEBHOOK_ENDPOINT_CHANGED`: the endpoint changed meanwhile; read it again and repeat the removal.`Conflict`

Response: ErrorCode

Field descriptions come from the OpenAPI contract; field names and values are identical in both languages.

deleteWebhookEndpoint: Response
Field	Description
`code`requiredType: string
`message`optionalType: string

Delivery history

get/v1/webhook-endpoints/{webhookEndpointId}/deliveries

Scopewebhooks:read

The latest 100 deliveries to the endpoint, newest first, with the attempt count, the next attempt and the outcome of the last one (`lastStatusCode`, `lastFailureCode`).

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

curl -X GET "https://api.bokapos.rs/v1/webhook-endpoints/287978af-8d23-4e51-8c51-59d60c5fb9c3/deliveries" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

200OK

{
  "items": [
    {
      "id": "4b6f2c1e-8a3d-4f5b-9c7e-1d2a3b4c5d6e",
      "eventId": "5c7a3d2f-9b4e-4a6c-8d1f-2e3b4c5d6e7f",
      "eventType": "receipt-delivery.failed",
      "status": "pending",
      "attempts": 2,
      "nextAttemptAt": "2026-11-02T09:41:20.000Z",
      "lastAttemptAt": "2026-11-02T09:36:20.000Z",
      "lastStatusCode": 502,
      "lastFailureCode": "HTTP_STATUS",
      "createdAt": "2026-11-02T09:35:19.800Z",
      "updatedAt": "2026-11-02T09:36:20.000Z"
    },
    {
      "id": "9fbe86a6-4d6a-4529-b162-ccacc98771a5",
      "eventId": "21c0738c-e29c-480f-92a9-fb88a99dc514",
      "eventType": "fiscal-document.fiscalized",
      "status": "succeeded",
      "attempts": 1,
      "nextAttemptAt": null,
      "lastAttemptAt": "2026-11-02T09:14:04.120Z",
      "lastStatusCode": 200,
      "lastFailureCode": null,
      "createdAt": "2026-11-02T09:14:03.640Z",
      "updatedAt": "2026-11-02T09:14:04.120Z"
    }
  ]
}

The first delivery got 502 twice and waits for its next attempt; the second succeeded on the first attempt.

Parameters

listWebhookDeliveries: Parameters
Field	Description
`webhookEndpointId`requiredIn: pathType: uuid

Responses

listWebhookDeliveries: Responses
200OK	Deliveries`WebhookDeliveryList`
404Not Found	Resource does not exist within the authenticated tenant scope`ErrorCode`

Response: WebhookDeliveryList

Field descriptions come from the OpenAPI contract; field names and values are identical in both languages.

listWebhookDeliveries: Response
Field	Description
`items`requiredType: array<WebhookDelivery>
`id`requiredType: uuid
`eventId`requiredType: uuid
`eventType`requiredType: string
`status`requiredType: string	Values`pendingsendingsucceededfailedcancelled`
`attempts`requiredType: integer	>= 0
`nextAttemptAt`requiredType: date-time \| null (nullable)
`lastAttemptAt`requiredType: date-time \| null (nullable)
`lastStatusCode`requiredType: integer \| null (nullable)
`lastFailureCode`requiredType: string \| null (nullable)	Values`HTTP_STATUSREDIRECT_NOT_FOLLOWEDTIMEOUTCONNECTION_FAILEDDNS_FAILEDTLS_FAILEDTARGET_NOT_PUBLICINVALID_TARGET`
`createdAt`requiredType: date-time
`updatedAt`requiredType: date-time

Resend a delivery

post/v1/webhook-endpoints/{webhookEndpointId}/deliveries/{webhookDeliveryId}/resend

Scopewebhooks:write

One more attempt right away, outside the retry schedule, for a succeeded, failed or cancelled delivery of an enabled endpoint. A failed resend does not start a new retry series.

POST/v1/webhook-endpoints/{webhookEndpointId}/deliveries/{webhookDeliveryId}/resend

curl -X POST "https://api.bokapos.rs/v1/webhook-endpoints/287978af-8d23-4e51-8c51-59d60c5fb9c3/deliveries/9fbe86a6-4d6a-4529-b162-ccacc98771a5/resend" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

{
  "id": "9fbe86a6-4d6a-4529-b162-ccacc98771a5",
  "eventId": "21c0738c-e29c-480f-92a9-fb88a99dc514",
  "eventType": "fiscal-document.fiscalized",
  "status": "pending",
  "attempts": 1,
  "nextAttemptAt": "2026-11-02T12:00:00.000Z",
  "lastAttemptAt": "2026-11-02T09:14:04.120Z",
  "lastStatusCode": 200,
  "lastFailureCode": null,
  "createdAt": "2026-11-02T09:14:03.640Z",
  "updatedAt": "2026-11-02T12:00:00.000Z"
}

Contract notes (OpenAPI)

Allowed for succeeded, failed and cancelled deliveries of an enabled endpoint. A failed resend does not start a new retry series.

Parameters

resendWebhookDelivery: Parameters
Field	Description
`webhookEndpointId`requiredIn: pathType: uuid
`webhookDeliveryId`requiredIn: pathType: uuid

Responses

resendWebhookDelivery: Responses
202Accepted	Delivery queued again`WebhookDelivery`
404Not Found	Resource does not exist within the authenticated tenant scope`ErrorCode`
409Conflict	`WEBHOOK_DELIVERY_IN_PROGRESS` while the delivery is still queued or sending, `WEBHOOK_ENDPOINT_DISABLED` when the endpoint is switched off, `WEBHOOK_DELIVERY_CHANGED` when the delivery changed meanwhile.`Conflict`

Response: WebhookDelivery

Field descriptions come from the OpenAPI contract; field names and values are identical in both languages.

resendWebhookDelivery: Response
Field	Description
`id`requiredType: uuid
`eventId`requiredType: uuid
`eventType`requiredType: string
`status`requiredType: string	Values`pendingsendingsucceededfailedcancelled`
`attempts`requiredType: integer	>= 0
`nextAttemptAt`requiredType: date-time \| null (nullable)
`lastAttemptAt`requiredType: date-time \| null (nullable)
`lastStatusCode`requiredType: integer \| null (nullable)
`lastFailureCode`requiredType: string \| null (nullable)	Values`HTTP_STATUSREDIRECT_NOT_FOLLOWEDTIMEOUTCONNECTION_FAILEDDNS_FAILEDTLS_FAILEDTARGET_NOT_PUBLICINVALID_TARGET`
`createdAt`requiredType: date-time
`updatedAt`requiredType: date-time

Send a test event

post/v1/webhook-endpoints/{webhookEndpointId}/test-events

Scopewebhooks:write

Queues one `webhook-endpoint.test` event for this endpoint only, signed like every other. It never appears in the feed and never goes to another endpoint. The endpoint must be enabled.

POST/v1/webhook-endpoints/{webhookEndpointId}/test-events

curl -X POST "https://api.bokapos.rs/v1/webhook-endpoints/287978af-8d23-4e51-8c51-59d60c5fb9c3/test-events" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

{
  "eventId": "60e081b9-14f3-46e9-a26b-531436ddc947"
}

The endpoint shortly receives a signed request with type: webhook-endpoint.test and data: { webhookEndpointId }; the outcome shows in the delivery history.

Contract notes (OpenAPI)

The test event is never shown in the event feed and never sent to another endpoint.

Parameters

createWebhookTestEvent: Parameters
Field	Description
`webhookEndpointId`requiredIn: pathType: uuid

Responses

createWebhookTestEvent: Responses
202Accepted	Test event queued`WebhookTestEvent`
404Not Found	Resource does not exist within the authenticated tenant scope`ErrorCode`
409Conflict	The endpoint is disabled`Conflict`

Response: WebhookTestEvent

Field descriptions come from the OpenAPI contract; field names and values are identical in both languages.

createWebhookTestEvent: Response
Field	Description
`eventId`requiredType: uuid

Signing public keys

get/v1/webhook-signing-keys

Scopewebhooks:read

The Ed25519 public keys that verify the signature of every webhook request. Trust every listed key: during a rotation there are two, and every delivery carries one signature per key.

GET/v1/webhook-signing-keys

curl -X GET "https://api.bokapos.rs/v1/webhook-signing-keys" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

200OK

{
  "items": [
    {
      "id": "boka-2026-11",
      "algorithm": "ed25519",
      "publicKey": "whpk_tmKJ87mlOVyUIvJCGkDR/3Sndc35HZH6fQRJwdH/FO4="
    }
  ]
}

The key in this example is made up; read the real one from the response. The same key serves sandbox and production.

Contract notes (OpenAPI)

Trust every listed key. During a rotation two keys are listed and every delivery carries one signature per key.

Responses

listWebhookSigningKeys: Responses
200OK	Active public keys`WebhookSigningKeyList`

Response: WebhookSigningKeyList

Field descriptions come from the OpenAPI contract; field names and values are identical in both languages.

listWebhookSigningKeys: Response
Field	Description
`items`requiredType: array<WebhookSigningKey>
`id`requiredType: string
`algorithm`requiredType: const "ed25519"
`publicKey`requiredType: string	Standard Webhooks public key, whpk_ followed by the base64 raw 32-byte Ed25519 key. pattern ^whpk_[A-Za-z0-9+/]{43}=$