Delivery, retries and security

Delivery semantics

Each webhook delivery is a single HTTPS POST request. Emailgistics waits for your response before doing anything else with the message.

Per-attempt timeout

100 seconds

Maximum attempts

Up to 3 (one attempt only for any 4xx response)

Retried on

Connection errors, HTTP 5xx

Not retried on

Any 4xx response

429 + Retry-After

Honored, up to 10 seconds. Larger values are capped at 10 seconds.

If your endpoint returns HTTP 200 with "status": "error" in the body, that is treated as a logical failure, not a transport failure: the actions in the response (if any) are ignored, and no retry happens. Use this when your handler ran but couldn’t produce a useful action — a CRM lookup failed, a business rule said skip, etc.

If all 3 attempts fail, the failure is logged on the Emailgistics side and processing of the rule moves on. There is no customer-visible record of the failure today; a future Admin view will surface delivery history.

Backpressure

If your endpoint is overwhelmed, return:

HTTP/1.1 429 Too Many Requests
Retry-After: 10

Emailgistics will wait the indicated number of seconds before the next attempt, up to a maximum of 10 seconds. Values larger than 10 are capped at 10.

Source IP

Webhook traffic originates from a stable IP per region — see Regions and base URLs for the per-region addresses. Whitelist the IP for your region on your endpoint.

TLS

• HTTPS only — webhook URLs must use https://.
• TLS 1.2 or higher.

Secret validation

The webhook delivers a Bearer secret in the Authorization header:

Authorization: Bearer YOUR_WEBHOOK_SECRET

Validate this on every request:

• Reject (401) any request whose Authorization header doesn’t match your expected secret. Don’t accept unauthenticated requests.
• Use a constant-time comparison to avoid timing attacks.
• Store the secret in a key vault or environment variable. Never commit it to source control or log it.
• Use a secret of at least 16 characters including letters, digits, and symbols.

The secret is stored encrypted at rest. Once you save it, Emailgistics staff cannot read it back — only the running webhook delivery process can decrypt it.

Recommended endpoint behavior

• Idempotency. Emailgistics may retry a delivery on a connection error after your handler has already run. Make actions idempotent (or check whether the action has already been applied) to avoid duplicate effects.
• Fast acknowledge, slow process. If your processing is expensive, return quickly with status: "success" (no actions) and process asynchronously in your own queue. Emailgistics doesn’t currently support a “processed later” pattern with deferred actions.
• Logging. Log every webhook delivery you receive — timestamp, mailbox, conversation ID, what actions you returned. This is the only audit trail until Emailgistics provides one.
• Monitor 4xx and 5xx responses. A 4xx from your endpoint is treated as terminal — Emailgistics won’t retry, and you’ll lose the delivery if your endpoint was misconfigured.

What we don’t currently provide

These are real gaps you should know about when designing your integration:

• No customer-visible delivery log. You can’t see in Admin which deliveries succeeded, failed, or were dropped after retries. Track this yourself on your endpoint.
• No replay. Failed deliveries can’t be re-triggered.
• No exponential backoff between retry attempts. The three attempts run back-to-back as soon as each one finishes (or times out). A flaky endpoint can receive three quick consecutive requests. Use 429 + Retry-After if you need to throttle.