API keys and webhooks
Create keys for your own ERP, TMS or WMS, set up webhooks, and NAV keys for routes and addresses.
INTEGALL has two kinds of keys for external systems:
- API keys and webhooks for the INTEGALL API: read shipments, request transports, read invoices and receive messages when something happens. You find them at the bottom of SettingsIntegrations, on the card API and webhooks.
- NAV keys for the INTEGALL NAV server (routes and addresses). You find them on SettingsAPI keys.
The technical description for your IT partner is under Developers (API).
Create an API key#
- Go to SettingsIntegrations and scroll to API and webhooks. It also shows the API address and a link to the Technical description (OpenAPI).
- Choose + New API key.
- Fill in a Name (what is this key for?), for example ERP connection.
- Choose the Scopes: Read shipments, Request transports, Read invoices, Manage webhooks. Only give what the system needs.
- Optionally tick Sandbox key (writes are only validated, nothing is stored) to test first.
- Choose how long the key is Valid: until I revoke it, 30, 90 or 365 days.
- Enter the code from your authenticator app and choose Create key.
- The key is shown only once. Copy it with Copy, keep it safe (for example in a password vault) and choose I have saved it.
You can have at most 20 active keys.
Manage keys#
The table shows per key the Name, the Scopes (with Trial for a test key), the Status (Active, Withdrawn or Expired) and the Usage: when the key was last used and how many calls in the last 24 hours.
With Withdraw and Yes, revoke a key stops working immediately. To replace a key: create a new key, put it in your system and then revoke the old one.
Webhooks#
With a webhook, INTEGALL sends a message to your address as soon as something happens. Every message is signed (X-INTEGALL-Signature).
- Choose + New webhook.
- Fill in the Address (https), for example
https://erp.yourcompany.com/integall. The address must be https, with a public domain name (no IP address or internal name). - Choose the Events: Shipment status changed, Invoice final and Invoice paid.
- Enter the code from your authenticator app and choose Add webhook.
- The signing secret is shown only once. Give it to your IT partner, who uses it to verify every message.
Per webhook you see the last delivery with HTTP status, how many messages are queued and how many failed in the last 7 days, and the details under Recent deliveries.
- Send test message: a test message goes out within a minute.
- Resend failed: resends the failed deliveries of the last 7 days.
- Turn off or Turn on, and Delete.
A failed delivery is retried for about 28 hours. If your address does not answer for more than 24 hours, INTEGALL switches the webhook off automatically, with the reason. You can have at most 10 webhooks.
NAV keys#
SettingsAPI keys shows the NAV keys: keys for external systems (ERP, TMS) that request routes or addresses from the INTEGALL NAV server. The office and driver apps need no key; they use their own sign-in.
Permissions: Calculate routes, Search addresses, Map tiles and Override vehicle profile. Here too the key is shown only once and creating it asks for a fresh code.