Webhooks

Document webhooks notify your system when carrier-uploaded documents on a Carrier Portal order are processed or when the order's aggregate document status changes. They complement the order API described in Integration flows.

Base URLs

Purpose	Test	Production
Webhook registration (`POST /api/v1/webhooks`, etc.)	`https://api-test.spotgo.eu`	`https://api.spotgo.eu`
Carrier order data (`dataUrl` in webhooks — order GET, document download)	`https://carrier-test.spotgo.eu`	`https://carrier.spotgo.eu`

Authentication uses your company API key (X-Api-Key header), same as other public API calls.

1. Webhook registration

POST /api/v1/webhooks

Field	Value
Registration type (`eventType`)	`CarrierDocuments` (enum value `12`)
Scope	One subscription per company account and callback URL

Request example (test environment)

{
  "eventType": "CarrierDocuments",
  "callbackUrl": "https://your-system.example.com/webhooks/spotgo",
  "callbackAuth": {
    "type": "ApiKey",
    "apiKey": {
      "headerName": "X-Api-Key",
      "headerValue": "your-inbound-secret"
    }
  },
  "notificationsEmails": [
    "integrations@your-company.com"
  ]
}

Supported callbackAuth.type values: None, Basic, ApiKey, OAuth2.
callbackUrl must use HTTPS.

Response

{
  "subscriptionId": "53559882-b8cd-4f08-b3f4-efc71a9e0254"
}

Registration test ping

On create (and on PUT /api/v1/webhooks/{subscriptionId}/reset), SpotGo sends a connectivity test to your callback URL:

{
  "id": "771de42bf63f48f6b6e2ffaf253170cd",
  "subscriptionId": "53559882-b8cd-4f08-b3f4-efc71a9e0254",
  "event": "example.event.publish.test",
  "dataUrl": "https://api-test.spotgo.eu/api/v1/documents/test/771de42bf63f48f6b6e2ffaf253170cd"
}

Registration succeeds only if your endpoint returns a successful HTTP response to this test.

Existing `All` subscriptions

If you already have a webhook with eventType: "All", you will also receive carrier document events — no separate CarrierDocuments subscription is required.

Per-event filtering

Subscriptions are registered at the type level (CarrierDocuments), not per individual event. All three document events below are delivered to the same subscription. Filter on the event field in your handler if you only care about some of them (e.g. only carrier.document.accepted for Workflow A, or only carrier.document.processed for Workflow B).

Manage subscriptions

Method	Path	Purpose
`GET`	`/api/v1/webhooks`	List subscriptions
`DELETE`	`/api/v1/webhooks/{subscriptionId}`	Remove subscription
`PUT`	`/api/v1/webhooks/{subscriptionId}/reset`	Re-send test ping and reset failed-delivery counter

2. Events

SpotGo delivers an HTTP POST (JSON body) to your callbackUrl. The payload is intentionally small: use dataUrl to fetch the full order (including documents) with your API key.

Event	When it fires	Typical use
`carrier.document.processed`	After initial AI processing completes for the order — i.e. no documents remain in `Processing` on that order. Fires once for the whole order, not per split document. Failed classifications still count as "no longer processing".	Workflow B — review newly uploaded/classified documents (`GET` order → download via `.../content` → accept/reject via status API).
`carrier.document.accepted`	When the order's aggregate document status transitions to Accepted — every required document type has at least one accepted document.	Workflow A — trigger downstream automation when paperwork is ready.
`carrier.document.rejected`	When the order's aggregate document status transitions to Rejected — at least one required document type has all of its documents rejected.	Alert or retry flows when required paperwork cannot be accepted.

Important behaviour

id in the webhook body is the order orderId (GUID string). Persist this when you create/upsert orders.

dataUrl points to GET /api/v1/orders/{orderId} on the Carrier Portal order host (https://carrier-test.spotgo.eu in test, https://carrier.spotgo.eu in production) — not the webhook registration host (api-test.spotgo.eu / api.spotgo.eu).

Re-uploads can move an order through InReview → Accepted → InReview → Rejected over time; accepted/rejected events may fire more than once. Always treat dataUrl as the latest state.

There is no per-document webhook; document details are always loaded from the order response after notification.

Duplicate notifications are possible; design your consumer to be safe when the same event arrives more than once.

3. Webhook payload examples (test environment)

Documents processed (upload + AI classification finished)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "subscriptionId": "53559882-b8cd-4f08-b3f4-efc71a9e0254",
  "event": "carrier.document.processed",
  "dataUrl": "https://carrier-test.spotgo.eu/api/v1/orders/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Order documents accepted (aggregate)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "subscriptionId": "53559882-b8cd-4f08-b3f4-efc71a9e0254",
  "event": "carrier.document.accepted",
  "dataUrl": "https://carrier-test.spotgo.eu/api/v1/orders/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Order documents rejected (aggregate)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "subscriptionId": "53559882-b8cd-4f08-b3f4-efc71a9e0254",
  "event": "carrier.document.rejected",
  "dataUrl": "https://carrier-test.spotgo.eu/api/v1/orders/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Recommended handler flow

Receive POST on your callbackUrl.

Read event and id (orderId).

GET the dataUrl with your X-Api-Key to load the order and Documents (test: https://carrier-test.spotgo.eu, production: https://carrier.spotgo.eu).

For each document you need, call GET .../orders/{orderId}/documents/{documentId}/content on the same order host as dataUrl.

(Workflow B only) Update document status via POST .../orders/{orderId}/documents/{documentId}/status on the same order host.

1. Webhook registration#

Request example (test environment)#

Response#

Registration test ping#

Existing All subscriptions#

Per-event filtering#

Manage subscriptions#

2. Events#

3. Webhook payload examples (test environment)#

Documents processed (upload + AI classification finished)#

Order documents accepted (aggregate)#

Order documents rejected (aggregate)#

Recommended handler flow#