Incoming webhooks

The Incoming webhook module provides a flexible way for external systems (such as marketing automation providers or customer data platforms) to send customer information to the loyalty program. The incoming webhook messages are processed and registered as customer events in loyalty members' event histories based on the mapping configured under the module’s editor interface.

1 Configuring incoming webhooks
- 1.1 Blueprints
- 1.2 Name
- 1.3 Request
- 1.4 Filters
- 1.5 Action
- 1.6 Mapping
- 1.7 Response
2 Activating an incoming webhook
3 Managing incoming webhooks
- 3.1 Edit a webhook
- 3.2 Deactivate a webhook
- 3.3 Archive a webhook
4 Use cases
- 4.1 Point add
  - 4.1.1 Configuration
  - 4.1.2 Activation
  - 4.1.3 Webhook message
- 4.2 Point subtraction
  - 4.2.1 Configuration
  - 4.2.2 Activation
  - 4.2.3 Webhook message
- 4.3 Checkout accept
  - 4.3.1 Configuration
  - 4.3.2 Activation
  - 4.3.3 Webhook message
- 4.4 Checkout accept item
  - 4.4.1 Configuration
  - 4.4.2 Activation
  - 4.4.3 Webhook message
- 4.5 Assigning labels to customers upon opt-in
  - 4.5.1 Configuration
  - 4.5.2 Activation
  - 4.5.3 Webhook message
5 Logs

Find the configuration page by navigating to the Modules menu and searching for ‘Incoming webhooks' in the module list. The page will open to the list of already configured webhook settings.

Configuring incoming webhooks

Click the ‘Create new webhook’ option in the sidebar

Blueprints

Choose the ‘Blank' card to define unique settings
In case you have a live mParticle integration, you can also find prefilled blueprints for specific scenarios.
Click 'Create' at the bottom of the page

Name

Enter the name of the new webhook

Request

Use the dropdown menu to select the request method
PUT and POST methods are available.
Specify the endpoint
Enter the name of the endpoint where the request will be sent

Filters

Adding a filter is not mandatory, however, it is recommended to filter the requests coming to the webhook endpoint. This is to ensure you catch, route, and process the correct requests and ensure the endpoint cannot be abused with malicious intent.

Click the button to add a new filter criteria
All request attributes can be accessed in the filters, including headers and the ones sent in the request body. Use the prefixes headers and body respectively to access the attributes.
- headers example: if you would like to check for the attribute called request_original_date from the header, you will need to type headers.request_original_date.
- body example: to access the same attribute from the request body, add body.request_original_date

The system allows combining multiple filter criteria with AND and OR relations.

It is a good design practice to expect an authorization token either in the request header or in the body.

Use non-standard naming for the request attribute in which you expect this token to be present and rotate the tokens regularly. Always store your tokens in a key vault and do not expose them to unauthorized personnel.

Action

Select an event to be registered
The dropdown list shows all Antavo events that can be triggered.

Mapping

Click to add a new field mapping
- From
  Unlike filters, only attributes of the request body can be used which also suggests adding a body prefix to the attribute is unnecessary.
  Example: To access the variable called purchase_value from the body of the webhook message, you will need to type purchase_value in the ‘From’ field.
- To
  You might need to use the data prefix when mapping your request attribute to an event attribute, as Antavo events contain all information that is unique to an event under the data attribute.
  Example: if you were to try to recreate the profile event and you would like to map the first_name field from the request, you will need to type data.first_name in the ‘To’ field instead of simply typing first_name.
- Default
  This value will be added to data cells where the field value is empty.
- Replace values
  You can decide to overwrite certain data values in the webhook message with a new value.
  Use the value to replace and the new value fields to define which value should be replaced and what the target value is.

To map more than one value, click the button.

Response

Specify the response when the operation is successful or unsuccessful
Make sure to write a valid JSON string here. If you leave the success and/or error fields empty, the default messages will be added to the response.

Click ‘Create’ at the bottom of the page

Activating an incoming webhook

After saving for the first time, the webhook is created as inactive, which means the messages will not be operational and will appear only in the list of incoming webhooks in the Backoffice.
You can activate the webhook right away using the ‘Set active’ button on the upper right-hand side of the setup page and confirm the activation in the dialog that subsequently appears.

Managing incoming webhooks

Edit a webhook

Navigate to the Incoming webhooks page
Click the ‘Edit’ button of the webhook that you would like to update
Edit your webhook settings
Save your changes by clicking ‘Save’

Deactivate a webhook

Navigate to the Incoming webhooks page
Click the ‘Edit’ button of the webhook that you would like to update
Click ‘Set inactive’ at the top right corner of the page
Confirm your choice in the dialog that subsequently appears

Inactive wheels will not be returned by the Display API.

Archive a webhook

You have the option to delete inactive webhooks from the Backoffice by archiving them.

Navigate to the Incoming webhooks page
Click the ‘Edit’ button of the webhook that you would like to update
Click on the ‘Archive’ button on the upper right-hand side of the page
Confirm your choice in the dialog that appears

Archiving is irreversible. Once a webhook is archived, it cannot be restored anymore.

Use cases

This section shows examples to set up the point_add, point_sub, checkout_accept, checkout_accept_item events and a use case to label customers upon loyalty program registration.

Point add

Configuration

Request
- Name: Point add
- Method: POST
- Endpoint: endpoint1
- Action: Point add
- Filters: body.pointadd exists

Mapping
- From: clientID
  To: customer
- From: reason
  To: data.reason
- From: pointstobeadded
  To: data.points
Response
- Success message: {'ok':true}
- Error message: {'notok':false}

Activation

Click 'Set Active' button in the upper right corner

Webhook message

Send the below POST request to the URL https://api.antavo.com/beta/webhooks/custom/{account_id}/endpoint1

{
'clientID': 'ID of your customer',
'pointstobeadded': 'the number of points you wish to add',
'reason': 'reason for adding the points'
}

Point subtraction

Configuration

Request
- Name: Point sub
- Method: POST
- Endpoint: endpoint2
- Action: Point sub
- Filters: body.pointsub is greater than 0

Mapping
- From: clientID
  To: customer
- From: reason
  To: data.reason
- From: pointsub
  To: data.points
Response
- Success message: {'ok':true}
- Error message: {'notok':false}

Activation

Click 'Set Active' button in the upper right corner

Webhook message

Send the below POST request to the URL https://api.antavo.com/beta/webhooks/custom/{account_id}/endpoint2

{
'clientID': 'ID of your customer',
'pointsub': the number of points you wish to subtract,
'reason': 'reason for adding the points'
}

Checkout accept

Configuration

Request
- Name: Checkout accept
- Method: POST
- Endpoint: endpoint3
- Action: Checkout accept
- Filters: body.checkoutaccept exists

Mapping
- From: clientID
  To: customer
- From: transaction_id
  To: data.transaction_id
- From: total
  To: data.total
Response
- Success message: {'ok':true}
- Error message: {'notok':false}

Activation

Click 'Set Active' button in the upper right corner

Webhook message

Send the below POST request to the URL https://api.antavo.com/beta/webhooks/custom/{account_id}/endpoint3

{
'clientID': 'ID of your customer',
'transaction_id': 'ID',
'total': 'total value of the transaction'
}

Checkout accept item

Configuration

Request
- Name: Checkout accept item
- Method: POST
- Endpoint: endpoint4
- Action: Checkout accept item
- Filters: body.checkoutacceptitem exists

Mapping
- From: clientID
  To: customer
- From: transaction_id
  To: data.transaction_id
- From: total
  To: data.total
- From: product_id
  To: data.product_id
- From: subtotal
  To: data.subtotal
- From: quantity
  To: data.quantity
Response
- Success message: {'ok':true}
- Error message: {'notok':false}

Activation

Click 'Set Active' button in the upper right corner

Webhook message

Send the below POST request to the URL https://api.antavo.com/beta/webhooks/custom/{account_id}/endpoint4

Assigning labels to customers upon opt-in

Configuration

Request
- Name: Optin labels
- Method: POST
- Endpoint: optin_labels
- Action: Opt in
- Filters: body.optin_labels exists

Mapping
- From: customerID
  To: customer
- From: optin_labels
  To: data.email
- From: first_name
  To: data.first_name
- From: last_name
  To: data.last_name
- From: labels
  To: data.labels
Response
- Success message: {'ok':true}
- Error message: {'notok':false}

Activation

Click 'Set Active' button in the upper right corner

Webhook message

Send the below POST request to the URL https://api.antavo.com/beta/webhooks/custom/{account_id}/optin_labels

Logs

The logs are displayed under the Logs tab of the module with the following information:

Timestamp - date of the webhook message trigger
Request
POST /webhooks/type/{brandID}/name
Time - processing time of the webhook message
Status code
Detailed request
Detailed response

In addition, there is always a possibility to check also the event log of the given customer under the Events tab under Customer insights.