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.

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

{ '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

{ '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

{ '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

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

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.