Event streaming integration

Developer assistance needed

You’ll need help from your development team to set up the integration. Please share this guide with them.

Integration overview

Integration type

Source: Data is sent from Pushwoosh to your system via HTTP or gRPC based on configured event triggers.

How does the integration work?

Pushwoosh transmits communication event data (e.g., push/email activity) to a client-defined endpoint. Data is sent in batch streams at scheduled intervals or upon reaching a minimum batch size.

Data is only sent if it matches the selected events, platforms, and optional filters (campaign/message codes, live activity). The client endpoint must be ready to receive and optionally respond with a status.

Glossary

Endpoint URL: Server-side endpoint which allows receiving requests. The client may specify a port if needed.

Examples:

• https://clientdomainname.com/webhook_endpoint
• https://clientdomainname.com:8081/webhook_endpoint

List of synchronized entities

• Communication statistics events (e.g., Push Sent, Email Delivered)
• Post events: events your app sends to Pushwoosh via postEvent, streamed separately from communication statistics events

Use cases

• Real-time engagement tracking

Monitor user interactions such as push sent, email opened, or message delivered as they happen, enabling immediate visibility into campaign performance.

• External analytics integration

Stream events to third-party analytics platforms for centralized reporting and analysis.

• Automated user workflows

Trigger actions in external systems (like CRMs or marketing automation tools) based on user behaviors, e.g., send a follow-up message when a user opens an email.

• Device list sync

Remove devices from your own database when they can no longer receive messages. See Sync unregistered devices to your system.

Setting up the integration

To set up the integration:

1. In your Pushwoosh account, go to Settings > 3rd party Integrations, find Event streaming integration, and click Configure.

2. In the window that opens, fill out the necessary fields.

Enter endpoint URL

In the Endpoint URL field, enter the full URL where events will be sent, including the protocol and port if applicable.

Example

• https://clientdomainname.com/webhook_endpoint
• https://clientdomainname.com:8081/webhook\_endpoint

Select events

From the Events dropdown, select at least one event. If none are selected, validation will fail. The list of events is managed by the backend and may change over time.

Provide authorization credentials

If required by your server, enter the complete value for the Authorization header in the Authorization field.

Examples:

• Bearer your_token_here

• Basic base64encoded_credentials

Note

The value is inserted as-is into the Authorization header (HTTP) or gRPC metadata. Ensure there is a space between the auth scheme and the token.

Choose transport type

From the Transport type dropdown, choose the delivery protocol for event transmission: HTTP or gRPC. Each has specific behavior and configuration.

HTTP

With the HTTP transport type, Pushwoosh sends data in batches based on one of the following conditions:

• At least 100 events are ready to be sent, or

• One hour has passed since the last transmission.

After sending the data, the connection is closed once a successful response is received.

If the server responds with a 5xx error, Pushwoosh will retry the request according to the defined retry policy.

Retry mechanism

Attempt	Delay
1st	1 second
2nd	3 seconds after 1st try
3rd	8 seconds after 2nd try

If all retries fail, the request is discarded.

Timeout

The default timeout for a request is 30 seconds. This can be customized upon request via support.

View example

gRPC

The gRPC transport type uses bidirectional streaming for data transmission. Learn more in the gRPC documentation.

A stream is opened when either of the following conditions is met:

• At least 1,000 events are ready for delivery
• One hour has passed since the last stream was opened

The stream is closed after the events are sent. This ensures that a new stream is not opened for each individual event in a short time.

See protobuf specification

Retry mechanism
Each event includes a unique uuid. If an event fails:

1. The response must include a status not equal to "Success"
2. The original uuid from the request must be included

Pushwoosh will retry delivery based on this response.

Connection settings

Advanced options like TLS, keep-alive, or retry policies are configured manually via support and may require development involvement.

Enable post events

This toggle is off by default, so only communication statistics events stream. To also stream events your app sends to Pushwoosh via postEvent, turn on the Allow post events toggle.

From the Post events field that appears, select which of your account’s events to stream. At least one event is required while the toggle is on. If your account hasn’t sent any events yet, this list is empty until you call postEvent at least once.

Note

Post events are sent to the same Endpoint URL entered above, and reach it regardless of platform: the Platforms and Advanced filters sections below apply only to communication statistics events, not to post events.

In-app impressions and clicks also travel through this post event stream, as PW_InAppShow and PW_InAppClicked. Each appears in the Post events list only after it has fired at least once for the account, same as any other post event.

Select platforms

In the Platforms section, select at least one platform to activate event streaming.

Supported platforms include:

• iOS, Android, macOS, Windows, Amazon, Safari
• Chrome, Firefox, Internet Explorer, Huawei
• Email, SMS, Line, Xiaomi, WhatsApp

Configure advanced filters

In the Advanced filters section, refine the event delivery criteria using filters:

• Live activity events: Enable to receive live activity events. These events contain only metadata including live_activity_id.

• Campaign filters: Filter by campaign code. Only events tied to these campaigns will be delivered.

• Message filters: Filter by message code. Only events tied to these messages will be delivered.

After completing all the required fields, click the Apply button to save and activate your integration.

Note

Configuration changes will take effect within 15 minutes after submission.

Tip

For advanced settings such as custom timeouts or gRPC configurations, please contact support.

Request details and example

Endpoint	https://exampleclientendpoint.com/webhook_endpoint
HTTP Request	POST
Authentication	No
Request type	Source
Request meaning	Send requests to the webhook endpoint
Headers	Content-Type: application/json

Request body example

{
  "event_name": "Email Opened",
  "message_code": "E682-E6D92B9A-53E24868",
  "campaign_id": 961048,
  "platform": "Email",
  "payload": "Welcome to Headway! 👋",
  "application_code": "XXXXX-XXXXX",
  "hwid": "user@example.com",
  "user_id": "USER_ID",
  "timestamp": 1723799271,
  "journey_title": "",
  "journey_point_title": "5_Welcome_ID_new",
  "attributes": null
}

Attributes

Among communication statistics events, attributes populates only for push events, with channel-specific content (Android, iOS, and so on) for the platform that push was sent to. Email and SMS events carry only the top-level fields (event_name, platform, payload, and so on). attributes is null for those events. Within a populated attributes object, fields outside the event’s own platform are omitted rather than sent as empty values. See webhook.proto for the full field list.

A post event carries its attribute key/value pairs in attributes.event_attributes instead. message_code and payload stay empty, because a post event isn’t tied to a message or campaign.

Caution

attributes.geozone is deprecated: the source property is an object, not a number, so this field never carried a real value. Read the actual geozone from attributes.geozone_data instead. The old field stays in the contract for clients with existing gRPC stubs.

Response
At the moment, the response code and body are ignored.

Sync unregistered devices to your system

If you keep your own copy of the device list, for example in a CRM or a customer data platform, stream the PW_DeviceUnregistered post event to find devices that Pushwoosh can no longer reach. Pushwoosh sends this event when a device loses its push subscription: the push service reports the token as invalid, the app unregisters the device through the SDK, or the user unsubscribes from emails.

Start from an integration that is already set up, with an Endpoint URL entered and at least one platform selected. Then:

1. In the integration settings, turn on Allow post events. See Enable post events.
2. In the Post events field, select PW_DeviceUnregistered.
3. To also learn about devices that get a push token, select PW_DeviceRegistered.
4. Click Apply. The change takes effect within 15 minutes.

PW_DeviceUnregistered appears in the Post events list only after it has fired at least once for the account. Until then, you can’t select it.

Keep these limits in mind when you process the events:

• Match devices by hwid or user_id, not by push token. The event carries the device’s hwid, user_id, and platform, but no push token and no reason for the unregistration. An expired token and an SDK unregistration look the same.
• Token rotation sends no event. PW_DeviceRegistered fires only when a device without a push token receives one. When a device replaces its token with a new one, neither event fires, so a list keyed by token keeps collecting stale tokens.
• An email unsubscribe doesn’t delete the device. For email, the address stays on the device and Pushwoosh only marks it as unsubscribed. When the user unsubscribed through a link in an email, attributes.event_attributes also carries the message_code and campaign_id of that email.

Because a batch that fails all HTTP retries is discarded, some events may never reach your endpoint. Reconcile your list periodically: export the segment of devices you target to CSV and compare it with your records. Exporting a segment requires the Personal data permission in your role.

How do you know that the integration is working?

You will start receiving requests from Pushwoosh at your configured endpoint.