How to connect WhatsApp to your ERP, CRM or store with an API and webhooks

Customer service happens on WhatsApp, but the rest of the business lives in other systems: the ERP with orders and stock, the CRM with the customer list, the online store, the booking system. As long as they don't talk to each other, someone bridges them by hand. They copy the order number, paste it in the chat, go back to the system and update the status.

This article has two parts. The first is for people making the decision: what's worth automating and how to think about the integration. The second is for developers: how to call the API, receive webhooks and do it safely.

Part 1: for decision makers

What an integration solves

An integration removes the manual work of repeating the same information in two places and makes WhatsApp react to what happens in your other systems, and the other way around. Some generic examples:

• Order notice. The store marks an order as shipped, and the customer gets a message without anyone typing it.
• Billing and reminders. The ERP's finance module creates an invoice that's about to fall due, and a message goes out with the notice.
• CRM contact. When the customer moves to another stage in the chat, the CRM receives the information.
• Booking tied to your site or your own system. A clinic checks free slots and creates the appointment from the system it already uses.
• Orders and tickets. Store orders and support tickets come into the inbox and get their status updated.
• Team alerts. An event (new conversation, disconnected channel, ticket past its deadline) triggers a notice in another system.

API or webhook, which one

The difference is who takes the initiative.

Almost every integration uses both: the webhook says something happened, and the API does the action in return.

What to ask before you start

1. Which process will be automated? Pick one, the one that eats the most time today.
2. Which system is the source of truth? Stock, price, order status: decide who is in charge.
3. Who deals with it when it breaks? Every integration fails at some point. Someone has to see it and fix it.
4. What happens if a message goes out twice or doesn't go out? Depending on the case, the damage is small or large.
5. Did the customer agree to get the message? Automating the send doesn't remove WhatsApp's rules or data protection law.

Availability

The API and webhooks are available from the Pro plan up. Each integration uses the company's own credentials, which keeps one account's data separate from another's. For agencies, that means one integration per client, each with its own token.

Part 2: for developers

The full documentation, with the format of each resource, is at /docs/api. What follows are the concepts and the precautions.

Authentication: one token per company

In Settings, in the developers area, you create API tokens. Each token belongs to one company and is sent in the header Authorization: Bearer <token>. The value is shown only once, so store it in a secrets manager.

Each token has abilities: read, create and change, send messages and store orders. Create one token per system and give it only what it needs. If a system is compromised, you revoke one token without touching the others.

What the API does today

• Inbox. Read conversations, messages and contacts, send text messages and mark a conversation as resolved.
• Calendar. List calendars and free slots, read appointments, create, reschedule and cancel.
• Site leads. Read leads, when the Forms or Lead capture app is installed.
• Orders. Read and create orders and change their status, when the Orders app is installed and the token has the orders ability.
• Tickets. Read, create, change status and add notes, when the Tickets app is installed.

Two limits so you don't promise too much. Sending a message is text only: POST /api/v1/messages, with the destination (a conversation or a phone number) and the text, up to 4096 characters. There is no media sending through the API. And there is no route just for adding or editing contacts: the API reads existing ones, and a new contact is created along with a message to a phone number, an appointment or an order carrying that number.

One detail about sending: the response is 202, meaning the message was accepted for sending, not necessarily delivered. If the company's number is disconnected, the call returns a 409 error. A message to someone who has never talked to the company may be held by the product's safeguards, and the response gives the reason.

Idempotency: don't send the same thing twice

Networks drop, timeouts happen, and your system retries. Without care, the customer gets the same payment notice twice.

POST requests that send or create something (message, appointment, order, ticket) accept the optional Idempotency-Key header. With the same key, the same token and the same body, the second call returns the first response, marked with Idempotent-Replayed: true, instead of repeating the action. The key lasts 24 hours and can be up to 100 characters. If you reuse the key with a different body, you get an error. Only successful responses are stored, so a call that failed validation can be fixed and resent with the same key.

How to build the key: use something that identifies the business fact, like order-1234-shipped, not a new random number on every attempt. That way a retry of the same event always lands on the same key.

Webhooks: receiving events

You register a public HTTPS address and choose the events, or all of them. Each company can have up to 10 addresses. Internal addresses are not accepted. Events include:

• messages: message.received, message.sent, message.status;
• conversations: conversation.opened, conversation.assigned, conversation.resolved;
• contacts: contact.created, contact.updated, contact.stage_changed;
• capture: lead.created, form.submitted, pixel.event;
• calendar: appointment.created, appointment.rescheduled, appointment.cancelled;
• orders, deals and tickets, when the matching app is installed;
• channel.status, when the connection state of the number changes.

Each delivery is a POST with JSON containing id, event, created_at and data. The headers carry X-Integra-Event, X-Integra-Delivery (the delivery identifier) and X-Integra-Signature.

Verify the signature

Anyone who finds your address can send a fake POST. The signature prevents that. The header has the format t=<timestamp>,v1=<hex>. The v1 value is an HMAC-SHA256 of <timestamp>.<raw body>, using the webhook secret as the key. The secret is shown only once, when you create the webhook.

Do it like this:

1. Read the request's raw body, before parsing it into an object.
2. Compute the HMAC with your secret and compare it to v1 in constant time.
3. Check that t is recent, for example within a few minutes, to block replays of an old capture.
4. If anything doesn't match, respond with an error and don't process.

Answer fast and handle repeats

IntegraWhats expects a 2xx response within 10 seconds and does not follow redirects. Do the minimum on receipt: validate, write to a queue and respond. Process later.

When a delivery fails, through a network error or a non-2xx status, it is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours. After 50 failures in a row the address is switched off and you have to reactivate it in the dashboard.

This has an important consequence: the same event can arrive more than once, and you can't count on order. Store the X-Integra-Delivery of each processed delivery and ignore repeats. And look at the current state of the data, not just the sequence of events.

Production checklist

• One token per system, with the minimum abilities.
• Secrets outside the code and outside the repository.
• Idempotency-Key on every call that creates something.
• Signature checked on every webhook.
• Fast 2xx response and queued processing.
• Deduplication by delivery identifier.
• An alert for when the webhook is switched off because of failures.
• Testing with a test WhatsApp number before going live.

How to get started in IntegraWhats

On the Pro plan or higher, open Settings and the developers area, create a token with the abilities you need and register the webhook address. There is a button to send a test event. The documentation lives at /docs/api.

Frequently asked questions

Can I send images or documents through the API?

Not today. The API sends text messages. Media is still sent by the team from the inbox.

Can I add a contact through the API?

There is no route just for that. The contact is created along with another action: sending a message to a new phone number, booking an appointment or recording an order with a phone number.

How many webhooks can I register?

Up to 10 addresses per company, each with the events you choose.

What happens if my server goes down?

Deliveries are retried for up to 24 hours, following the retry schedule. After that the delivery is marked as failed, and after 50 failures in a row the address is switched off. To catch up on what you missed, query the API for the current state of the data.

Can an agency integrate several clients?

Yes. Each company has its own tokens and webhooks, so each client gets its own integration, isolated from the others.