Manage Webhook

A webhook is the HTTPS endpoint on your side that receives tracking notifications. Each partner has exactly one webhook.

Method	Path	Description
`GET`	`/webhook`	Show the registered webhook
`POST`	`/webhook`	Register the webhook
`DELETE`	`/webhook`	Delete the webhook and all its subscriptions

Register a Webhook

POST /webhook

Body Parameters

Field	Type	Required	Description
`url`	`string`	Yes	A valid absolute URL, max 2048 characters. Must accept `POST` with a JSON body

cURL


curl -X POST https://delivery.spedisci.online/api/v2026-04/webhook \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "url": "https://partner.example.com/hooks/delivery" }'

Request


{
  "url": "https://partner.example.com/hooks/delivery"
}

Response


{
  "id": 12,
  "url": "https://partner.example.com/hooks/delivery",
  "secret": "9Xk2pQvR7tLmZ4nB8sD1yF6hJ3wC5aE0gU7iO2rT",
  "is_active": true,
  "created_at": "2026-04-15T10:22:31+00:00",
  "message": "Store the secret now — it is used to verify webhook signatures and will not be shown again."
}

The secret is returned only in this 201 response. It is the key used to sign every notification — store it immediately in your secret manager. There is no way to read it back. If you lose it, delete the webhook and register a new one.

Response Codes

Code	Description
`201`	Created — webhook registered, `secret` returned
`401`	Missing or invalid access token
`409`	A webhook already exists — delete it first
`422`	Validation failed (`url` missing, not a URL, or longer than 2048 characters)


{
  "code": 409,
  "status": "error",
  "message": "A webhook already exists. Delete it before creating a new one."
}

Show the Webhook

GET /webhook


curl https://delivery.spedisci.online/api/v2026-04/webhook \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json"


{
  "id": 12,
  "url": "https://partner.example.com/hooks/delivery",
  "is_active": true,
  "failures_count": 0,
  "created_at": "2026-04-15T10:22:31+00:00",
  "updated_at": "2026-04-18T14:32:06+00:00"
}

Response Fields

Field	Type	Description
`id`	`number`	Webhook identifier
`url`	`string`	The registered endpoint
`is_active`	`boolean`	`false` once the webhook has been auto-disabled after repeated failures
`failures_count`	`number`	Consecutive failed notifications. Reset to `0` on the first success
`created_at`	`string`	ISO-8601 creation timestamp
`updated_at`	`string`	ISO-8601 last update timestamp

The secret is never returned by this endpoint.

Response Codes

Code	Description
`200`	OK
`401`	Missing or invalid access token
`404`	No webhook registered

Delete the Webhook

DELETE /webhook


curl -X DELETE https://delivery.spedisci.online/api/v2026-04/webhook \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json"


{
  "code": 200,
  "status": "success",
  "message": "Webhook deleted."
}

Deleting the webhook cascades: every tracking subscription attached to it is deleted too. You have to re-subscribe your shipments after registering a new webhook.

Response Codes

Code	Description
`200`	Webhook deleted
`401`	Missing or invalid access token
`404`	No webhook registered

Re-enabling a Disabled Webhook

If your endpoint fails 10 notifications in a row it is set to is_active: false and stops receiving traffic. To recover:

Fix your endpoint so it answers 2xx.
DELETE /webhook, then POST /webhook again — this issues a new secret and resets the failure counter.
Re-create your subscriptions.

Alternatively, contact supporto@spedisci.online to have the existing webhook re-activated without changing the secret.