Rules and webhooks

A rule tells Mixmax "when this happens, do that". It has a trigger (an event, or a schedule), an optional filter that the event must match, and one or more actions. The action most integrations want is a webhook: Mixmax sends the event to your HTTPS endpoint as a JSON POST.

You can build rules in the Mixmax app under Rules, or with the API. Both create the same thing, and a rule made in one shows up in the other.

Set up a webhook with the API

Create the rule, paused so nothing fires while you set it up. For example, every email sent to [email protected]:

curl -X POST https://api.mixmax.com/v1/rules \
  --header "X-API-Token: <your token>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Forward support emails",
    "trigger": { "type": "event", "eventName": "message:received" },
    "filter": "{\"to.email\":{\"$regex\":\"^support@yourcompany\\\\.com$\",\"$options\":\"i\"}}",
    "isPaused": true
  }'

filter is a JSON-encoded string, not an object. See POST /v1/rules for the triggers, the events you can use and the filter syntax.

Add a webhook action to the rule:

curl -X POST https://api.mixmax.com/v1/rules/<rule _id>/actions \
  --header "X-API-Token: <your token>" \
  --header "Content-Type: application/json" \
  --data '{ "type": "postToWebhook", "webhookUrl": "https://example.com/mixmax" }'

The response includes signingSecret, which starts with whsec_. This is the only time you see it, so store it with your receiver. See Verifying webhooks.

Turn the rule on with PATCH /v1/rules/<rule _id> and {"isPaused": false}.

What your endpoint receives

Each time the rule runs, Mixmax sends one POST with the event as a JSON body. The fields depend on the event; to see them, point a test rule at an endpoint you control and trigger it with test data. Avoid public request-inspection services for real events, since the body can contain your contacts' data. The body includes eventName, unless the action has transforms.

Signed. Each delivery carries X-Mixmax-Webhook-Id, X-Mixmax-Timestamp and X-Mixmax-Signature. Verify them before you trust the body.
Timeout. Mixmax waits up to 30 seconds. Reply with any 2xx as soon as you've stored the event, and process it afterwards.
Retries. If your endpoint times out, can't be reached or replies with something other than 2xx, Mixmax retries about every 5 minutes, a limited number of times. If the last attempt fails, the rule is paused and its owner is emailed.
A 404 pauses the rule at once, without retrying, because Mixmax reads it as "this URL no longer exists".
At least once, in no particular order. The same event can arrive more than once, so make your handler safe to run twice.

After fixing your endpoint, turn the rule back on with PATCH /v1/rules/<rule _id> and {"isPaused": false}.

Managing secrets

To replace a webhook's secret, PATCH /v1/rules/<rule _id>/actions/<action _id> with {"rotateSigningSecret": true}. The response shows the new secret once, and the old one stops working at once.
Webhook actions created before Mixmax began signing deliveries have no secret and are sent without the X-Mixmax-* headers. Rotating gives them one.
Listings never show a secret, only its last four characters as signingSecretLastFour.

Call webhooks

The call events (call:started, call:completed and call:recording-available) are documented as webhooks in this reference, under Calls. call:recording-available is set up by workspace admins under Admin center > API keys, not as a rule.