Transaction Feeds

Persistent delivery is the pull-based alternative to standard webhooks.
Instead of SpotGo calling your public endpoint, it writes a notification to the transactions feed for your application to retrieve.

Step 1 — Create a subscription

Create a subscription with POST /api/v1/webhooks.

Field	Value
`eventType`	A specific event type, such as `Order` or `Fine`.
`callbackAuth.type`	`Persistent`

Endpoint: POST /api/v1/webhooks

{
  "eventType": "Order",
  "callbackAuth": {
    "type": "Persistent"
  }
}

A successful request returns 200 OK:

{
  "subscriptionId": "5f7a79b6-5698-460f-9384-f1abea4e8390"
}

After you create a subscription, poll the transactions feed to learn which documents are ready for you.
You have two ways to do this.

Approach A — Retrieve based on document status

Used to retrieve requested documents based on their status property.

Endpoint parameters are as follows:

Parameter	Required	Description
`eventType`	Yes	The subscribed event type, for example `Order`.
`status`	No	Status of the document (e.g. `Ready` ).
`nextToken`	No	Continuation token from a previous page of results.

1. Poll for Ready items

Endpoint: GET /api/v1/transactions-feed?eventType=Order&status=Ready

{
  "items": [
    {
      "transactionId": "8dfc76b7-218b-4d5a-aed6-a73f6c680d20",
      "documentId": "ec85ca8c-e42a-4752-9fd5-e050b8e19115",
      "eventType": "Order",
      "event": "order.process.success",
      "status": "Ready",
      "createdAt": "2026-07-14T10:00:00Z"
    }
  ],
  "nextToken": "nextTokenExample"
}

Each feed item points at a document. Use documentId to fetch the full document details for that eventType.

If the response includes nextToken, call the same endpoint again with that token inside nextToken parameter until every page is read. Keep eventType and status=Ready the same while paging.

2. Acknowledge after processing

When you have successfully processed an item, acknowledge it:

Endpoint: PUT /api/v1/transactions-feed/{transactionId}

Use the transactionId from the feed item. The request has no body.

A successful acknowledgement returns 204 No Content and moves the item from Ready to Completed.

Acknowledge only after successful processing. Acknowledging an unknown or already completed transaction returns 404 Not Found.

Approach B — Retrieve based on creation time

Used to retrieve requested documents based on their createdAt property.

Endpoint parameters are as follows:

Parameter	Required	Description
`eventType`	Yes	The subscribed event type, for example `Order`.
`dateFrom`	No	UTC timestamp (`YYYY-MM-DDTHH:MM:SS`). Returns items with `createdAt` at or after this time. Cannot be in the future.
`nextToken`	No	Continuation token from a previous page of results.

Poll from a point in time

Endpoint: GET /api/v1/transactions-feed?eventType=Order&dateFrom=2026-07-14T09:30:00Z

Example:

An Order created at 2026-07-13T09:29:59Z is not returned (before dateFrom).

An Order created at 2026-07-14T10:00:00Z is returned.

Use documentId from each feed item to retrieve the full document from the endpoint based from eventType .

For the next poll, from the array take the last item's createdAt and pass it as dateFrom.

If nextToken is present from the query, to get next page, pass it to nextToken parameter with the same eventType and dateFrom.

Transaction Feeds

Step 1 — Create a subscription#

Approach A — Retrieve based on document status#

1. Poll for Ready items#

2. Acknowledge after processing#