Synchronizing subscriber data with other systems

Summary

Echobox supports subscriber data synchronisation via a bidirectional transfer of data:

• Outbound (Echobox → external system)
• Echobox emits webhooks when subscriber events occur: subscribes, unsubscribes, bounces, etc.
• Inbound (external system → Echobox)
• Your system calls Echobox's endpoints to push changes the other way, when a change is required for a specific subscriber: updating a subscriber’s fields, changing their subscription status or deleting them.

A middleware layer typically sits between the two, handling authentication, data transformation, and retries.

For further in-depth guides please see:

• Operating on Subscriber Data in Echobox
• How to configure webhooks for your Echobox campaign
• https://docs.echobox.com/reference/getting-started-email

What does the middleware do?

Both the outbound (from Echobox) and inbound (to Echobox) data flow through the same middleware layer, which is responsible for:

• Authenticating with each system
• Transforming payloads between expected request formats for Echobox's and the external applications endpoints
• Handing errors and retries

Is the middleware required?

To provide highly secure endpoints, Echobox's endpoints authenticate using a short-lived Client Service Token (CST) which isn't natively supported by no-code tools like Zapier or Make. This means a middleware application is required to handle the authentication with Echobox endpoints.

For more details on the authentication flow see: https://docs.echobox.com/reference/getting-started-email

Outbound: webhooks

Webhooks are configured per campaign, not at the property level, and each webhook supports one event type.

If you need to sync multiple event types out of a single campaign, you'll need to set up multiple webhooks pointing at the same (or different) callback URLs.

See here for more details: How to configure webhooks for your Echobox campaign

Setting up a webhook

In Echobox navigate to a campaign and go to Integrations → Webhooks → Create webhook, then:

1. Select the campaign
2. Give the webhook a name
3. Choose the event type it should fire on
4. Choose POST or PUT as the delivery method
5. Enter the callback URL. The endpoint on your side (or your middleware) that will receive the event
6. Save, then enable it

Requests from Echobox are sent with User-Agent: http://www.echobox.com, which you can use to identify inbound webhook traffic if needed.

Event types

Webhooks in Echobox support the following event types:

• Subscribe
• Unsubscribe
• Open
• Click
• Hard bounce
• Complaint

The payload will be a flat object with the email address and event type in question.

{
 "emailAddress": "john.doe@echobox.com",
 "eventType": "SUBSCRIBE"
}

The campaign the event is attributed to can be inferred from the callback URL, as each webhook is campaign specific.

Inbound: Echobox endpoints

For changes flowing from your external system into Echobox, use the endpoints covered in Operating on Subscriber Data in Echobox. The ones most relevant for subscriber data synchronization are:

See our API reference for full details: https://docs.echobox.com/reference/getting-started-email

Example

Use case: keep a CRM's contact records aligned with Echobox subscription status, and push CRM field changes into Echobox.

1. CRM → Echobox: when a subscriber’s data changes in the CRM, the middleware picks this up (via the CRM's own webhook or polling), transforms it into a payload that can be accepted by the Echobox Update Subscriber endpoint, and issues the call to the endpoint.
2. Echobox → CRM: an "unsubscribe" webhook is configured on the relevant campaign(s), pointing at the middleware's callback URL. When a subscriber unsubscribes, Echobox sends the event; the middleware receives it, maps the Echobox subscriber to the corresponding CRM contact, and updates a "subscribed" field on that record. Since webhooks are per-campaign and per-event-type, a property with many campaigns will need one unsubscribe webhook configured per campaign.