Incoming webhooks
The User Manual has moved! For the most up-to-date information, please visit our new site at docs.antavo.com.
We're committed to providing you with the best resources, and our new site offers an enhanced experience with the latest documentation. Thank you for your understanding and continued support.
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
- 2 Activating an incoming webhook
- 3 Managing incoming webhooks
- 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
- 4.1 Point add
- 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 prefixesheaders
andbody
respectively to access the attributes.headers
example: if you would like to check for the attribute calledrequest_original_date
from the header, you will need to typeheaders.request_original_date
.body
example: to access the same attribute from the request body, addbody.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 abody
prefix to the attribute is unnecessary.
Example: To access the variable calledpurchase_value
from the body of the webhook message, you will need to typepurchase_value
in the ‘From’ field.To
You might need to use thedata
prefix when mapping your request attribute to an event attribute, as Antavo events contain all information that is unique to an event under thedata
attribute.
Example: if you were to try to recreate theprofile
event and you would like to map thefirst_name
field from the request, you will need to typedata.first_name
in the ‘To’ field instead of simply typingfirst_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.
© Copyright 2022 Antavo Ltd.