Connect other systems with the API and webhooks

With the API another system reads and records information in Nori: customers, items, documents, payments, inventory or the CRM. Webhooks work the other way around: Nori tells that system when something happens, for example when an invoice is posted or a payment arrives.

Everything is set up in Administration › Integrations › API and webhooks. You need the permission API: integration tokens for other systems for tokens and API: outbound webhooks for webhooks.

Integration tokens

An integration token is the key a system uses to call the API. Each token belongs to one system and has its own technical user:

• It takes no license.
• It cannot sign in to Nori: not on the web nor in the app; it only calls the API.
• It does what its role allows, and only within its scopes. If the role lacks a permission, so does the token, even if the scope includes it.

Create a token

1. In Integration tokens click New token.
2. Give it a name that says which system uses it, for example "Online store".
3. Choose the role. If it should do little, first create a role with only those permissions.
4. Tick the scopes: only what the other system needs. For example, an online store usually needs Read items, prices and stock and Create and change sales documents.
5. If the other system always calls from the same IPs, write them in Allowed IPs (one per line; networks like 201.150.10.0/24 work too).
6. If it is temporary, set a date in Expires on.
7. Click Create token and copy it right away: it is shown only once.

The other system sends it on every call in the header Authorization: Bearer <token>. The technical documentation of the API is behind the API documentation button.

Change or revoke a token

The list shows when and from which IP each token was last used. Change or revoke changes its scopes, IPs or expiry, or revokes it. A revoked token stops working at once.

If the other system gets "This token lacks the scope for this operation", the message says which scope is missing: add it if that system should do it.

Webhooks

A webhook is an address of the other system where Nori sends a notice when something happens. You can choose among these events:

• Documents: created, posted and cancelled.
• Incoming payments: received and cancelled.
• E-invoicing: CFDI stamped and cancelled.
• Home deliveries: when their status, date or carrier changes.
• Customers: created and changed.
• Inventory: item changes and stock changes (grouped by minute so there is not one notice per movement).

Create a webhook

1. In Webhooks click New webhook.
2. Type the other system's URL. It must start with https:// and be a public address.
3. Tick the events it cares about.
4. Click Create webhook and copy the secret: it is shown only once. The other system uses it to check that the notice comes from Nori (header Nori-Signature).
5. Click Send test to confirm the other system answers.

Deliveries and retries

The webhook's detail shows its Deliveries: date, event, status, answer and attempts. View shows what was sent and what the other system answered; Send again sends it once more.

If the other system does not answer well, Nori retries for almost a day (8 attempts, further apart each time). If it fails many times in a row, the webhook turns itself off and the administrators get a notice. Check the other system, send a test and turn it back on.

Change the secret

Change secret makes a new one and shows it once. For 24 hours Nori signs with both, so you have time to update the other system without missing notices.

CRM automation webhooks

The Notify another system action of the CRM automations also signs what it sends and retries it if it fails. It uses its own secret, which you make in the CRM automation webhooks section of this same screen.

If you don't see…

• The API and webhooks option in the menu: your role needs one of the two API permissions. Ask an administrator (roles and permissions).
• The token after creating it: it cannot be shown again. Revoke it and create another one.
• A notice arriving: check in Deliveries whether it failed and what the other system answered, and that the webhook is Active.
• That it lets you save the URL: it must be https://, without user or password, and cannot point to an internal network.