API keys and webhooks

Modulix can exchange data with your other systems, such as an accounting package, a data warehouse or an e-commerce site.

• API keys and OAuth clients let another system call the Modulix API on behalf of your organization, with the permissions you grant.
• Webhooks send events to another system as they happen: a contact created, an invoice changed, a person joining.

This page explains how administrators set them up. For the API itself (endpoints, formats, examples), developers can read REST API.

Before you begin

• To manage API keys and OAuth clients, you need Manage API keys (core.apikeys.manage).
• To manage webhooks, you need Manage webhooks (core.webhooks.manage).
• Owners and administrators have both by default.

Key concepts

• Scope: a permission key that an API key or OAuth client is allowed to use, for example contacts.contact.read. Wildcards are allowed: contacts.* covers every permission of the Contacts module. You cannot grant scopes you do not have yourself.
• API key: a single secret string, starting with mx_, that a system sends with each request. Simple to set up.
• OAuth client: a client ID and a client secret that a system exchanges for short-lived access tokens (valid one hour). Use it when the other system supports the OAuth 2.0 client credentials flow.
• Webhook: a URL in another system that Modulix calls with a signed JSON message when an event happens.

Keys, clients and webhooks belong to the organization you create them in, and only see and send its data.

API keys

In the sidebar, under Administration, select API keys. The API keys tab is open.

Create an API key

1. Select New key.
2. Enter a Name that says what the key is for, for example Accounting sync.
3. In Scopes, enter the permission keys the integration needs, separated by commas or spaces, for example contacts.contact.read, sales.*. You find permission keys on the Roles and permissions page, under each permission's label.
4. Select Create key.
5. Modulix shows "Copy your new key now — it will not be shown again." Select Copy and store the key in the other system or a password manager.

A new API key, shown once.

warning

Treat an API key like a password: anyone who has it can use your organization's data within its scopes. Modulix only keeps a fingerprint of the key and cannot show it again. If you lose it, revoke it and create a new one.

The other system sends the key with every request, in the X-Api-Key header or as Authorization: Bearer mx_….

The list shows each key's Name, the start of the Key (mx_1a2b3c4d_…), its Scopes, when it was Last used and when it was Created.

Revoke an API key

1. Select Revoke on the key's row.
2. Confirm: "Integrations using this key stop working immediately."

Modulix shows Key revoked. Revoke keys you no longer use, and when someone who knew a key leaves.

OAuth clients

On the API keys page, select the OAuth clients tab.

Create an OAuth client

1. Select New client.
2. Enter a Name, for example Data warehouse.
3. Enter the Scopes its access tokens will carry, as for an API key.
4. Select Create client.
5. Modulix shows "Copy the client secret now — it will not be shown again." Copy the Client ID and the Client secret.

OAuth clients and the token URL.

The Client credentials flow card below the list gives what the other system needs: the Token URL (https://your-server/api/v1/oauth/token) and an Example request. The other system sends its client ID and secret to the token URL and gets an access token valid for one hour. It then calls the API with Authorization: Bearer <token>, and asks for a new token when it expires.

To stop a client, select Revoke on its row. Its access tokens stop working immediately.

Webhooks

In the sidebar, under Administration, select Webhooks.

Create a webhook

1. Select New webhook.
2. Enter a Name, for example ERP sync.
3. Enter the URL that will receive the events, for example https://erp.example.com/hooks/modulix. Use https:// for anything outside your own network.
4. Under Events, choose what to send:
   • Everything: every event, including those of modules enabled later.
   • For a record type (grouped by module), All events, or only Created, Updated or Deleted.
   • Organization events: Person added to the organization, Person removed from the organization, Module enabled, Module disabled.
   • Other patterns: an event name, a prefix ending in .* (for example contacts.* for a whole module), or * for everything. Select Add.
5. Leave Active on to start sending right away.
6. Select Create.
7. Modulix shows the Signing secret: "Copy the signing secret now — it will not be shown again." Copy it into the receiving system, then select Done.

Choosing the events a webhook sends.

The receiving system uses the signing secret to check that requests really come from Modulix. The Payload, signatures and retries panel at the bottom of the Webhooks page explains how, with an example.

What the receiving system gets

Each event is a POST request with a JSON body that contains the event name, when it happened, and its data (for records, the record's ID and values). The request carries these headers:

Header	Content
X-Modulix-Event	The event name, for example contacts.contact.created.
X-Modulix-Delivery	A unique ID for this delivery.
X-Modulix-Timestamp	When it was sent, in Unix seconds.
X-Modulix-Signature	sha256= followed by the HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with the signing secret.

The receiving system must answer with a 2xx status within 10 seconds. Otherwise Modulix tries again after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then marks the delivery as failed.

Manage webhooks

The list shows each webhook's Name, Events and an Active switch. Turn the switch off to pause a webhook (Webhook paused) and on again to resume it (Webhook activated). Events that happen while a webhook is paused are not sent later.

The actions button (…) of a webhook offers:

Action	What it does
Edit	Changes the name, URL, events or Active switch.
Send a test ping	Sends a ping event now, to check the URL and the signature check.
Rotate the secret	Creates a new signing secret, shown once. Deliveries are signed with it right away: update the receiving system as soon as you have copied it.
Delete	Stops sending events to the URL and deletes its delivery history.

Check deliveries

Select Deliveries on a webhook's row. The Deliveries of name panel shows the latest 50 deliveries, refreshed every 5 seconds.

The delivery history of a webhook, with retries.

Status	Meaning
Queued	Waiting to be sent, or waiting for its next attempt (the panel says when).
Sending	Being sent now.
Delivered	The receiving system answered with a 2xx status.
Failed	Every attempt failed. The panel shows the last error.

Select a delivery to see its Payload and the receiving system's Response. To send a delivery again, for example after fixing the receiving system, select Redeliver. Modulix sends it as a new delivery.

If the panel says "Nothing sent yet. Send a test ping to try the URL.", no event matched the webhook yet.

Good to know

• Webhook URLs must start with https:// or http:// and cannot contain a user name or password. For security, Modulix refuses to call private or local network addresses.
• Workflows can also call a URL as one of their steps, with their own conditions. See Workflow automation.
• Creating, changing and revoking keys, clients and webhooks are recorded in the audit log.
• The full API reference (OpenAPI) is available on your server at /api/docs.

Permissions

Permission	What it allows	Granted by default to
core.apikeys.manage (Manage API keys)	Create and revoke API keys and OAuth clients.	Owner, Administrator
core.webhooks.manage (Manage webhooks)	Create, change, test, pause and delete webhooks, and see their deliveries.	Owner, Administrator