Skip to content
Engentra

Documentation

Build with Engentra

Connect customer data, business events, and communication channels to build automated journeys with workflows and AI.

Engentra API & webhooks guide

Send customer activity into Engentra, automate the next conversation and receive updates in your own system.

The Engage API is the developer interface behind Engentra. Use it when your store, CRM or internal application knows something your messaging team should act on: a price was quoted, an order was packed or a customer needs a follow-up. Your system records the event; Engentra matches enabled workflows and keeps the resulting conversation in the team inbox.

1. Prepare the workspace

Connect a WhatsApp or Instagram channel and configure a workflow before sending events. A recorded event alone does not guarantee a message: workflow conditions, channel rules, consent and plan limits still apply. For a hosted store, check the existing Shopify or WooCommerce integration first.

2. Keep your integration key on the server

Create a key in Settings → API keys and store it as a server secret. Send it in the X-API-Key header. Integration keys can use /v1/events and /v1/customers; they cannot read inbox messages, configure workflows or send arbitrary replies. Those operations require a signed-in user with the appropriate role. See authentication and permissions.

3. Record a business event once

Run on your server

curl -X POST https://api.engentra.io/v1/events \
  -H "X-API-Key: $ENGAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+2348012345678",
    "name": "Ada Obi",
    "type": "order.packed",
    "data": { "orderNumber": "1042" },
    "idempotencyKey": "order-1042-packed"
  }'

Reuse the same idempotency key when retrying the same business event. Use a different key for a different event. Check recorded and matchedWorkflows in the response before assuming automation ran. The API quickstart explains the response, and the events reference covers the fields.

4. Receive signed updates through webhooks

An owner can add a public HTTPS receiver in Settings → Webhooks. Subscribe to events such as message.received, message.status or sale.created, or an event type recorded by your own integration. Store the endpoint secret when it is first shown. Verify the signature against the original request bytes before processing.

Follow the webhook reference for the exact signature format, timestamp checks, delivery identifiers and retry behavior. Make your receiver tolerate duplicate deliveries so a retry does not create a second CRM task or stock update.

Business events and payment confirmation serve different purposes

Recording an event named payment.succeeded does not settle an Engentra payment request. Provider payment confirmation is verified separately. Do not treat a custom event or a customer returning from checkout as proof that money was received.

5. Verify the complete journey

  1. Record a unique test event and check that the expected workflow matched.
  2. Check the intended conversation and delivery status in the inbox.
  3. Confirm your webhook receiver accepts valid signatures and rejects invalid ones.
  4. Retry the event and webhook delivery; confirm your system creates no duplicate work.
  5. Handle rate limits and retain the request ID from API errors for support.

Next

Run the API quickstart →

Create your first event and inspect the result.