Webforce generic webhook

Purpose:

This walkthrough will guide you through setting up your Generic Webforce Webhook within the CRM. This webhook can create a lead and associate it with the following information:

Billing and shipping addresses
Phone numbers
Tags
Order notes

Pre Requisites:

CRM Access

Creating the webhook

Navigate to the Integrations tab within the CRM, then click the button to add a new integration.

in the search engine we place "webforce" and press configure

We place the name with which we want to identify the integration and press save

Once the integration is configured, we copy the url of the webhook and we will be able to send POST requests to this url

From this view you can also activate or deactivate the integration with the switch and pressing save

Payload request for the webhook

The webhook requires data in a specific format. Below is a sample of a complete payload.

{
    "contact": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com"
    },
    "phone": {
        "country": "US",
        "number": "+15124713434"
    },
    "billing_address": {
        "first_name": "John",
        "last_name": "Doe",
        "line": "11801 Stonehollow Drive",
        "line2": "line two",
        "city": "Austin",
        "state": "TX",
        "zip_code": "78758",
        "country": "US"
    },
    "shipping_address": {
        "first_name": "John",
        "last_name": "Doe",
        "line": "My shipping line address",
        "line2": "line two",
        "city": "Austin",
        "state": "TX",
        "zip_code": "78758",
        "country": "US"
    },
    "order": {
        "id": 123,
        "type": "success",
        "date": "2024-07-01 17:23:54",
        "subtotal": 100,
        "shipping": 8,
        "tax": 6,
        "total": 114,
        "items": [
            {
                "title": "Product one Red",
                "quantity": 2,
                "total": 50
            },
            {
                "title": "Product two White",
                "quantity": 1,
                "total": 50
            }
        ]
    },
    "additional_tags": [
        "tag1"
    ],
    "exclude_from_sms_automation":false
}

You don’t need to provide all of the sample information. The webhook is capable of creating only the pieces detected in the request.

Lets analyze every piece in the payload:

Contact object: This is the only mandatory object. You need to provide at least the email and the first name of the contact to be able to create a lead.
Phone object: If one of the two phone fields are missing the phone is not going to be created.
- Country: Must be in 2 character format.
- Number: Can be in international format, at least the 10 phone digits with no special characters are needed. Examples of valid phones:
  - +15124713434
  - 5124713434
Billing/Shipping address: For creating an address all of its fields except the line2 are required.
- Country: Must be in 2 character format.
- State: Must be in 2 character format.
- City: Maximum 100 characters length.
- Line: Maximum 255 characters length.
- Line2: Maximum 255 characters length.
- Zip code: Maximum length of 20 characters. Ensure the zip code format matches your country's requirements (e.g., 5 digits for the US).
Order: Another optional field, if provided it will generate an order note within you contact profile.
- Id: The id of your order in your external platform.
- Type. The status type of the order. For example: failed, success, refund. There is no a specific set of values here, just provide the one in your external platform.
- Date: When the order was created in your external platform. It must be provided in the format Y-m-d H:i:s. See example payload.
- Subtotal: Optional.
- Shipping: Optional..
- Tax: Optional.
- Total: The only needed amount field in the order.
- Items: Optional array, but when provided must have this structure.
  - Title: Item’s product name. Every item name will be used to generate a tag for the contact.
  - Quantity: Item’s quantity sold.
  - Total: Item’s amount charged.
Additional tags: Array of tags to be also attached to the contact.
Exclude from SMS Automation: (optional) Default is True and if not specified any SMS automation will ignore this event and no SMS will be sent. Change to False in order to Send the SMS.

We will always respond to the webhook request with a 200 status and a valid field in the response body. If you send an invalid request (missing the basic contact object information), this field will be set to false; otherwise, it will be set to true.

Response body when success

{
    "valid": true
}

Response body when fail

{
    "valid": false
}