Skip to main content

Configure your Event and Webhooks

  • Updated

Journeys are run through a table-based knowledge base through Messaging Mode. All configurations are related back to a specific table found in Messaging. In this article, we discuss how to create a webhook, an HTTP request that transfers data when triggered by an event. This carries a message to a destination such as an SMS. 

Webhooks are used for real time notifications, so your system can be updated right when the event takes place.

Setting up Campaigns
As you know, Journeys is an orchestrator for the marketing actions we want to make for a specific person. Once we design the Journeys and decide what we want to do in each circumstance, we need the users to start their journey. To do so, we need to call Journeys with the required info about the user, so it knows we want to start a journey for that person.

Currently, while we work on the Event system, we need to send the signals to Journey using the API directly. One way of doing this is to use MS WebHook Campaigns and triggers. Let’s see how that would work:

  1. Create a WebHook Campaign in a folder of our convenience, in the same MS account used for provisioning the Journey account.

- Messaging Campaign

- Select the right table

- Event Triggered

- Webhooks channel

 

  1. Go to API Posts in the left side menu. 

 

 

  1. Create a new API Post by clicking in the star right to the search box. Make sure the table is the same.
  2. Then, in the next screen, add the Primary Key column of the table, for Recipient is RecipientID:

 

 

  1. Check the REST API Only checkbox below. Please uncheck Sanitize Data Fields. 

 

  1. Click Save and then click Save and Make Public.
  2. Return back to the campaign and click on Add Trigger.
  3. Select API Post in the selector that will open: 

  1. Click Of a specific API Post, and search and select the new one just created.
  2. Enter the specifics for Journey Signaling. To do so, go to the Message section and enter the following:

 

- URL: https://api-us.journey.engageplatform.com/api/engine/p/temporal/signalms{journeyrunid} 

this can be found in your journey once it has been publishied by going to JOURNEY SETTINGS > JOURNEY PUBLICATION > JOURNEY ENDPOINT. 

- Http Method: POST

- Content Type : application/json

- Data Type: Body Text

Configuring webhooks for Events
Below, in the body section, you need to enter the Event Payload. The Event Payload is the data that tells Journeys about the Event and is formatted as JSON. In here you will add properties which can be used by your conditions [such as Decision steps] in order to personalize your journey.

Here is an example that shows you how to structure your JSON.

Note: Some data is the same for all webhooks, but other data uses variables [e.g. cart total] that you can drag and drop from the variables menu. In this example we’ve highlighted this in yellow. 

 

{

   "specversion": "1.0",

  "dataschema": "evt:campaign/v1",

  "type": "event.dispatch",

  "id": "474062ae-e647-4317-9c76-66f0696f4a81",

  "source": "msg:na",

  "time": "2023-05-24T07:31:09.332Z",

  "event": "event.dispatch:dispatch_thee",

  "accountId": "415",

  "data": {    

     "journeyRunId" : "3b7b18b562493543cd75bec9aeb4c13b",       

    "profileId" : "{(pk_recip_id)}",

"amount" : 123,

    "discount": 29,

    "date" : "2023-06-07T11:05:00+02"

  }

}

Let’s see the important fields and what values to set. The other fields are included so you can familiarize with the real events. However, they are not used here for now so you can leave the example values:

  • event: this is the event name you set in the Start Node or in any other node which accepts events (like wait nodes, or update nodes). This is, this is the “signal” you want to send to Journey so it knows something happened and acts accordingly as designed.
  • accountId: This one is the Messaging account id. This is the current account id where you are adding this webhook campaign. It is not the user id, but the whole account id. If you are not sure of your id you can go to Web Management and click on Javascript API. In the new tab you can search or CustId:
  • data.profileId: This is the PK in the table for the user you want to run the Journey. In the Recipient table, it is the Recipient ID attribute. Iin your own tables, the PK has the internal name pk_[table name]_id and the label you decide to use. In this example, it is mapped to the PK in the table, which is the correct one to use. That pk corresponds to the recipient table, but you will need the one corresponding to the table you are using.
  • data.journeyRunId: Optionally, you can send or not send this id. If you send it, the call only affects that specific Journey, and if not included, it would affect all the Journeys in the JDX account, which use that event and are published. The best way to get the id is going into settings in JDX and checking the Journey Endpoint (remember this is only visible once published, as it is on publish when that ID is generated).

 

  1. You can add other fields inside data that you want to use inside the Journey. These can be mapped from the API Post or from the table (see MS doc for more info about that). Note the date format in the example, as that’s the current one accepted. You need to add as mapped values as with the profileId. You can also add fixed values as in the example above.

  1. Once you are happy with the JSON payload, you can go to the launching section. Make sure you deselect the checkbox : Require Approval before Sending messages.
  2. This campaign is now ready for saving and launching. If you get a message about the metadata, go to the Edit tab and click on Set Metadata, select the metadata needed, and click Accept.  Then save the campaign again and you should be able to launch the campaign now.

 

It will take some time for the campaign to be ready,  check the status in the Launch tab until it reaches the Waiting status and it is ready to get events. See MS doc for more info on other config options available.

Trigger and API Post

There are two main ways we are going to walkthrough in this guide. Please go to MS doc for more information about this.

Doing a Post to the Program API
  • For this, you will do a post to the MS API that will trigger the campaign:
    • URL https://[api domain]/services2/api/Recipients (please ask support for your domain if you do not know).
    • Operation POST.

- content type header application/json

  • Payload:  {“apiPostId”:"109","data":[{"name":"pk_recip_id","value":"30086"}]} 

Let’s see where those values come from and how to get them:

  • apiPostId: 109, this is the id of the Api Post created above for the Webhook campaign. You can see the IR going to the API Post in MS console. By clicking into Generate URLs, you can see the id at the end of the Post URL as seen in the following image:

  • Name: This is the name of the primary key in the table. In the default Recipient table that’s always pk_recip_id, in your tables, it will always be pk_[tablename]_id. If the internal table name is customers it will be pk_customers_id. 
  • Value: This is the value of the above pk for the specific row of the table you want to run the Journey.  
  • Authorization Header: You need to use the OAuth authentication (see MS API doc for information about how to get a valid token).
Using the public Post
  1. Open API Post.
  2. Go to the Edit tab, and in the left menu, select Tools > Generate URLs.
  3. Inside the panel, select the Post URL, something similar to:

Post URL http://atsqa.eccmp.com/ats/post.aspx?cr=415&fm=109. Then, you can add the field you mapped for profileId as s_[fieldName] in the example above it would be s_pk_recip_id

 http://atsqa.eccmp.com/ats/post.aspx?cr=415&fm=109&s_pk_recip_id=30086. You can add other fields as well and map them into the Payload the same way. 

 

This one does not need authentication.

Was this article helpful?
0 out of 0 found this helpful
Return to top

Related articles