Integrations: API keys and webhooks

API keys

System → Integrations → API keys. A key gives an outside program access to the site on your behalf, but only to what you tick. A key cannot do more than you can: if you lose a permission, the key loses it too.

1. Click add, give the key a name for yourself (“warehouse”) and tick the permissions.
2. Copy the key right away: it is shown once, the site stores only its fingerprint and cannot show the key again. If you lose it, issue a new one.
3. The program sends the key in the header Authorization: Bearer nx_… to addresses under /api/v1.
4. You can revoke a key at any minute: the program loses access with it immediately.

All the endpoints available to a key are described in an OpenAPI file: the “Download API description” button gives it to you for Postman and client generators. The file contains only the endpoints your permissions cover; the keys themselves are not in it. The program can fetch the same file on its own: GET /api/v1/openapi.json with a key. The /api/v1/me endpoint answers whose key this is, until when it is valid and which permissions it has right now.

Webhooks

System → Integrations → Webhooks. When something happens on the site, such as an order being paid or an account being created, the site reports it by itself to the address you specify. Messages go through a queue and are repeated if the other end did not answer; next to a webhook you can see the time of the last delivery and the number of failures in a row.

• The address must be external and complete, with https:// or http://. The site does not call addresses inside the server or the local network; this keeps a webhook from becoming a way into your network.
• Every message is signed: the X-Nex1on-Signature header is a sha256 signature of the message body, computed with your “signing secret”. The receiving side computes the same signature and so knows the message came from your site.
• “Issue a new secret” replaces the previous one; the receiving side must be reconfigured afterwards.
• The list of events depends on the enabled modules: no module, no events from it.