API and webhooks

Through the allverto API, shops, fulfilment providers, accounting tools or your own programs exchange data with allverto: items, stock, customers, orders, payments, shipping, returns, sales channels, invoices and purchasing. Webhooks report changes immediately to an address of your choice – for example "Order created" or "Stock changed".

You set everything up under Settings → API & webhooks. That's also where you'll find the complete Documentation of all endpoints.

#Before you start

• API keys and webhooks are managed by roles with the Manage API keys and webhooks permission – usually Owner and Administration. See Users and roles.
• A key gets at most the permissions you have yourself. If you later lose a permission, the key loses it too.
• The same applies to webhooks: you can only subscribe to events whose data you may read yourself – "Customer changed", for example, only with "View customers", "Invoice created" only with "View documents". allverto hides events without the matching permission.

#Creating an API key

1. Open Settings → API & webhooks, API keys tab.
2. Click Create key.
3. Enter a Name that lets you recognise the external system (e.g. "Shopify connection").
4. Choose the Permissions, e.g. "Read orders" and "Import orders". Only pick what the external system really needs.
5. Optional: restrict the key to one Company (it then only sees and writes orders and documents of that company), set an Expiry date and the Request limit per minute.
6. Click Create key. allverto shows the key (av_…) exactly once – copy it with Copy and store it in the external system.

In the row menu you can Copy prefix (so you can find the key again in the external system) and Revoke the key at any time. The API then rejects it immediately. The list shows when a key was Last used and from which IP address.

#Requests to the API

Every request carries the key in the header Authorization: Bearer av_…. The endpoints are under /api/v1, for example:

curl https://deine-firma.allverto.cloud/api/v1/orders?status=paid \
  -H "Authorization: Bearer av_…"

• Lists return { data, page: { nextCursor, hasMore } }. You fetch the next page with cursor=<nextCursor>. With updatedSince=2026-10-01T00:00:00Z you only get entries created or changed since then – ideal for regular syncs.
• Errors always have the form { error, message, fields } with a matching HTTP status (400 input, 401 key, 403 missing permission, 404 not found, 409 conflict, 429 limit).
• Idempotency: send a unique Idempotency-Key header with POST requests. If you repeat the request (e.g. after a network error), allverto doesn't book anything twice but returns the same response for 24 hours.
• Request limit: the default is 120 requests per minute and key. If it is exceeded, the API responds with 429 and Retry-After (seconds).
• Returns and sales channels: GET /api/v1/returns and /returns/{id} return returns with line items, reasons and refund (permission "Read returns"), GET /api/v1/channels the sales channels – the counterpart to channelId in orders and returns.

Changes made via the API appear in the Change log as "API: name of the key".

#Setting up webhooks

1. Webhooks tab, click Add webhook.
2. Enter a name and the receiver's Address (https://…) and choose the Events, e.g. "Order created", "Payment received", "Stock changed". With several companies you can restrict the webhook to one company – then orders, documents, returns and purchase orders of other companies are not sent to this address.
3. Click Save. allverto shows the secret for verifying the signature – this too only once.
4. Use Send test to check the connection. The result appears in the Delivery log.
5. New webhooks are inactive. allverto only sends real events once you click Activate – as with all syncs.

Events are created in the same transaction as the change: if a booking is aborted, no webhook goes out either. The content (data) has the same format as the API (e.g. GET /api/v1/orders/{id}, for returns GET /api/v1/returns/{id}).

On every delivery, allverto checks the current permissions of the person who created or last changed the webhook. If they lack the read permission for an event or no longer have active access, no payload goes out; the delivery log shows the delivery as failed with the reason. Whoever saves the webhook afterwards becomes the responsible person.

#Verifying the signature

Every call carries the header allverto-signature: t=<Unix time>,v1=<signature>. The signature is HMAC-SHA256 with the secret over t + "." + Body. Verify it against the unmodified body and discard calls whose time differs by more than 5 minutes.

#Failed deliveries

If the receiver doesn't respond with 2xx, allverto tries again – after 1 minute, 5 minutes, 30 minutes, 2, 6, 12 and 24 hours. After 20 failures in a row the webhook is automatically deactivated; you get a notification. In the Delivery log (period "Last 30 days" by default) you can see the status, response code and duration of each delivery and Resend it.

Webhooks may only call public addresses – internal targets such as localhost or private networks are blocked.