EmailgisticsAPI
Webhooks

Setting up a webhook

Define a webhook in Emailgistics Admin and attach it to a mailbox rule.

The Webhooks feature is off by default. Contact Emailgistics support to have it enabled for your account.

Once enabled, two roles are involved. System administrators create webhook definitions in Admin (URL, secret, included data). Mailbox administrators then attach those webhooks to rules on the mailboxes they manage.

Defining a webhook

The Add Webhook page in Emailgistics Admin

Sign in to Emailgistics Admin as a system administrator and select Webhooks from the menu.

Click Add Webhook and fill in:

  • Name — the label that appears when selecting the webhook in rules.
  • Endpoint URL — your HTTPS endpoint. The protocol is fixed to https://.
  • Secret — we recommend at least 16 characters mixing letters, digits, and symbols. Optional but strongly recommended. Sent in the Authorization: Bearer ... header on every delivery.
  • Mailboxes — the mailboxes whose rules can use this webhook. Mailboxes outside this set won’t see the webhook in their rule editor.
  • Include message text — if checked, Emailgistics includes the plain-text message body in the delivery payload as bodyText. Off by default.
  • Include Custom Fields — if checked, Emailgistics includes the conversation’s customFields map in the delivery payload, when values are present.

Click Create.

Click Test Webhook to send a canned sample received-event payload to your endpoint, signed with your configured secret. Emailgistics POSTs the payload, reads your response, and validates that it contains the required status and message fields.

  • On success, Admin shows “Success! Mock request sent and webhook response received and validated.” along with a summary of the actions your endpoint returned.
  • On failure, Admin shows the underlying error — connection error, non-200 from your endpoint, malformed JSON, missing status or message, or a status: "error" response (in which case your message is shown verbatim).

Attaching a webhook to a rule

The webhook only fires when a mailbox rule with a Use webhook action matches an incoming message. Create one in the mailbox’s Rules section:

Open the mailbox in Admin and go to Rules.
Add a new rule with whatever conditions you want — sender domain, subject keywords, an explicit “every message” rule with no conditions, etc.
Add a Use webhook action and pick your webhook from the list. Only webhooks that include this mailbox in their definition appear here.
Save the rule.

The webhook now fires whenever a matching message arrives.

Rotating the secret

Rotate the webhook secret periodically. Coordinate the swap so traffic isn’t dropped:

Update your endpoint to accept either the old or the new secret. Roll the change out to all instances.
Edit the webhook in Admin and update the secret to the new value.
Once you’ve confirmed live traffic is working with the new secret, update your endpoint to accept only the new value.

Permissions, briefly

RoleCan
System administratorCreate, edit, delete webhook definitions; pick which mailboxes can use each webhook.
Mailbox administratorUse a webhook in mailbox rules, but only webhooks whose definition lists their mailbox.

Webhooks overview

Run custom logic in your own systems when messages arrive in an Emailgistics mailbox.

Request payload

Everything Emailgistics sends to your endpoint when a message triggers a webhook.

On this page

Defining a webhookAttaching a webhook to a ruleRotating the secretPermissions, briefly