How to Use the Inaiy API and Webhooks

The Inaiy API lets your own systems, such as an online store, ERP, or CRM, send WhatsApp messages and read data from your workspace. Webhooks do the reverse: Inaiy calls your system when something happens, such as a message being delivered or a customer replying. To start, go to Settings → Developer, generate an API key, copy your connection details, and create a webhook endpoint for the events you need.

Give every connected system its own credentials. You can then rotate or revoke one without breaking the others.

Who this is for and what you need first

This guide is for developers and technical admins connecting another system to Inaiy.

You need:

• A plan that includes the API and webhooks. See Inaiy subscription plans.
• Developer Platform permission in your role. See WhatsApp agent roles.
• A secret manager to store keys, and an HTTPS endpoint if you will receive webhooks.
• Approved templates for messages sent outside the 24-hour window. See WhatsApp template approval.

Steps to connect to the Inaiy API

1. Open Developer settings

Go to Settings → Developer. Overview has three kinds of Credentials: API keys (callout 1) for server-to-server access, Webhooks for endpoints that receive events, and OAuth apps for apps that act on behalf of other workspaces.

Under Connection details:

• API base URL: all endpoints are under /api/public/v1.
• x-tenant-id (callout 2): your workspace ID. Send it with every request.

Under Channels, each WhatsApp number, Instagram account, and Messenger Page has an ID. Send it as channelId to choose which one a message comes from. Documentation links to the quickstart, API reference, and webhooks guide at inaiy.com/developers.

Zoom

2. Generate an API key

Open API Keys and click Generate key (callout 1). Enter a Key name that says what uses it, such as "Production CRM Integration", and choose an Environment: Sandbox keys start with wp_test_, and Production keys start with wp_live_.

The full key is shown once. Copy it into your secret manager and tick I have stored this API key securely. After that, Inaiy shows only the Key prefix, environment, and created date, plus Usage with when the key was last used.

To replace a key, click Rotate (callout 2). The current key stops working immediately and a new one is shown once, so update your system straight away. Deactivate pauses a key, and Delete removes it.

Zoom

3. Call the API

Send both headers with every request to the API base URL:

x-api-key: <your API key>
x-tenant-id: <your workspace ID>

Add channelId to message requests to choose the sending number. See the API reference for each endpoint, with parameters and examples.

4. Create a webhook

Open Webhooks and click Create webhook. Fill in:

• Name: what it is for, such as "Order system - message status".
• Endpoint URL (callout 1): your HTTPS URL, such as https://example.com/webhooks/inaiy.
• Description: optional.
• Events (callout 2): Message Sent, Message Delivered, Message Read, Message Failed, and Message Received. Pick only what you use.

Click Create webhook. A signing secret, starting with whsec_, is shown once. Store it with your API key.

Zoom

5. Verify each webhook request

Every delivery includes headers such as X-Inaiy-Event, X-Inaiy-Event-Id, X-Inaiy-Timestamp, X-Inaiy-Delivery-Id, and X-Inaiy-Signature. Use your signing secret to check the signature before trusting the payload, and reject old timestamps. The webhooks guide at inaiy.com/developers shows how.

Reply with a 2xx status quickly. Inaiy retries temporary failures, such as timeouts or a 503, so use X-Inaiy-Event-Id to skip events you have already handled.

How to confirm it worked

1. Send a test message through the API to your own number. It should arrive, and the key's Last used time should update.
2. Reply from your phone. Your endpoint should receive a Message Received event.
3. Check that your signature check accepts the request, and rejects it if you change one character of the body.

Common mistakes

1. Putting keys in code. Keys in a repository can leak. Store them in a secret manager, as the security notice on the API Keys page says.
2. One key for everything. If one system leaks a shared key, rotating it breaks all of them. Create a key per system.
3. Slow webhook handlers. Doing heavy work before replying causes timeouts and retries. Reply 2xx first, then process the event in the background.

Related guides

• Choose a plan with API access in Inaiy subscription plans.
• Control who can manage keys with WhatsApp agent roles.
• Get templates ready for API sends with WhatsApp template approval.