Installation Instructions

1

Create a new Webhook Source in Converge

  1. In Converge, click on Create a new source
  2. Pick Server-side from the modal
  3. Name your server-side source: e.g. {Storename} Store Backend
  4. Click on Create Source.
2

Send a dummy event

  1. Click on your newly created Source. You will see a Webhook Endpoint URL and Webhook Token under the source configuration tab. webhook_config

The Webhook Token has been added recently to improve error messaging for easier issue diagnosis. Existing integrations that do not use a Webhook Token remain unaffected.

  1. The Webhook Endpoint is the URL where you’ll send the events to.
  2. Ensure the Webhook Token is included as a header using the header key X-Webhook-Token.
  3. Verify that your Webhook Source is working by sending a dummy Placed Order event request. Ensure the request meets the following parameters outlined in Manually instrumenting events
3

Verify that your event arrived in Converge

  1. Click on your newly created Source and choose the Logs subtab. You should see the event you just sent in there.

Manually instrumenting events

If the pre-built server integrations do not cover the applicable conversions from the Converge Event Spec; or if you want to add custom events from your website then you will need to manually instrument these using the Converge Pixel. You can use the Webhook source to manually instrument these events.

As a general rule, you should always aim to pass as many properties, profile_properties and aliases as possible

The webhook body has the following parameters:

ParameterTypeDescription
event_namestringRequiredThe name of the event
event_idstringRequiredThe ID of the event, used for deduplication
propertiesobjectRequiredThe event properties you want to pass, covering the Converge Spec and possibly your own custom properties.
profile_propertiesobjectRequiredThe profile properties
aliasesarray[string]RequiredAny aliases. Must contain at least one alias, with a maximum of 10 aliases allowed.
timestampdatetimeOptionalThe date and time when the event occurred. If not provided, the current time will be used. The timestamp can be expressed as a string in ISO 8601 format (e.g. "2024-09-02T12:34:56+00:00") or a UTC timestamp (e.g. 1725312229). The string representation must specify a timezone.

Event Spec

This integration does not auto-track any events by default. All events should be instrumented manually according to the Converge Event Spec.

You should typically implement Placed Order and Started Subscription events server-side. You can find a full list in the Converge Spec here