Skip to main content
Sign in MENU

Webhook Mapping

Dan Lawrence
  • Updated

Webhook Mapping is the process of matching incoming data from an external source, like a webhook, to specific fields in Bonzo. It helps organize and place the incoming information where it belongs, even if the names or formats differ between systems. By utilizing mapping, members can customize the flow of data through their webhooks, ensuring it aligns with their specific business needs. 

 

 

 

 Setting Up Webhook Mapping

  1. To access the Webhook Mapping tab, go to "Settings," select the "Integrations" tab, and click on "Webhooks." From there, choose the specific webhook you want to configure.

    Screenshot 2024-11-27 at 9.03.42 AM.png

     

  2. Once in the webhook, select the "Logs" tab at the top. Here you will see the entire webhook payload and you can identify the exact external field name (case-sensitive) that needs to be mapped or brought over into Bonzo.

    Screenshot 2024-11-27 at 9.06.22 AM.png

     

    For example the "external ID" field is a data point in the below webhook payload that does not have a corresponding default field in Bonzo. To ensure this data is utilized, members can map the "external ID" from the webhook payload to an existing field in Bonzo.

     

    Screenshot 2024-11-27 at 9.27.05 AM.png

  3. To add mapping for this external field in Bonzo, return to the webhook settings screen and click "Mapping," then "Add Mapping."

    Screenshot 2024-11-27 at 9.32.52 AM.png

    Select the Bonzo field from the existing "Field" dropdown menu or if the field doesn't exist, create a custom field by navigating to the "Company" tab and then to "Custom Fields and Views."

    Note: to learn more about creating a custom field, click on the link below. 
    People: Formatting, Custom Fields & Views, Importing


    In the "Key" field, paste the payload field ID (case sensitive). For example, to map "external ID," we would copy and paste the payload field ID into "Key" and then select a field for it to map to in Bonzo. 

    Screenshot 2024-11-27 at 9.43.13 AM.png

  4. Before clicking "Save" you have the option to set the mapping as "Payload Value" or "Static Value."

    Payload Value
     A payload value dynamically assigns data from the webhook payload to a Bonzo field. This means the assigned value changes based on the actual data received from each webhook event. For example, if the payload includes "external_ID": "12345", mapping the "Payload Field ID" (external_ID) to a Bonzo field (e.g., "Source") ensures the "Source" field is populated with 12345 for that specific event. This is ideal for scenarios where the data varies and needs to reflect unique information from each webhook.
    Static Value
    A static value is a fixed, manually set value applied to a Bonzo field for every webhook event, regardless of the data in the payload. For instance, mapping a "Source" field with the static value "SimpleNexus" ensures that every event populates "Source" with "SimpleNexus," providing consistency when specific data isn’t available in the payload. While payload values offer flexibility for dynamic data flow, static values provide uniformity across all events.

  5. Once you've mapped the fields and established the value, click "Save" to finalize the setup. 

  6. To test and verify the new mapping, trigger the webhook and review the incoming data in the webhook logs. Additionally, check the designated fields in Bonzo to ensure the data is correctly mapped and populated.


Important Tips and Reminders

  • Exact Match Required: Ensure the external field ID matches exactly as it appears in the webhook payload. Case sensitivity is critical.
  • Proper Formatting Required: Ensure that the data being sent to the mapped fields is properly formatted. For instance, if mapping a "Birthday" field, format the date as 12/12/2024, not December 12th, 2024, to ensure compatibility.
  • Custom Fields: If the desired field does not exist in Bonzo, create a custom field before mapping.
  • Static Values: Use static values sparingly, as they override dynamic payload data.
  • Test Thoroughly: After setting up mappings, verify the data flow by checking the mapped fields in Bonzo.
  • Tagging Not Supported: Webhook Mapping does not support mapping to tags directly. Use routing groups or pipeline stages for similar functionality.

 

 

Webhook Mapping is an essential feature for ensuring that your external data integrates seamlessly into Bonzo. By taking the time to configure mappings correctly, your team can maximize efficiency, maintain data accuracy, and streamline your workflows.

Note: To learn more about Integrations, click on the link below.
Integrations: General Overview

Related to

Related articles