Webhook API

The integration of the Webhook is addressed to receive entity data that will be created, validated updated or deleted organically, allowing the information and Wapping ID to be saved if needed.

The entity currently supported is the Customer, the Webhook will convey all the information relevant to the customer entity to have it updated in an external location.

🚧
This integration is not strictly needed as Wapping is an standalone CDP and doesn't require any external tools to function, it is offered in case more complex scenarios require to syncronize all the entity (customer) data externally.

📘
Once the platform is in production, customers can be created through various channels (WhatsApp, app, ecommerce, assisted registration, etc.). These can be initiated by the business or directly by Wapping.
All customer information (registration, validation, modification, deletion, etc.) will be sent via the webhook to keep the data updated in the business’s own systems in real-time.

The webhook integration has two differentiated parts. The first being the setup of the subscription, and the second the processing of the actual webhooks.

Setting up the subscription

First step is to check the different entities that can be subscribed to. In this case, the customer entity applies.
The available entities can be checked via /entities endpoint.

Next, the events to which one can subscribe within an entity can be viewed through the /entities/{code}/events. These events are usually Create, Update, Delete

After this, subscriptions can be created by providing a name and an endpoint via the subscription controller. The name will be to identify internally each subscription, and the endpoint must be a reachable url set up by the integrator so the webhook can call it.

For that subscription, it will be needed to subscribe (through the /subscription/{id}/subscribe to a specific event by specifying the subscription ID, entitycode, and eventCode.

The last step would be to activate it with the /enable method. This needs to be done once for each event you want to subscribe to.

In summary, the steps to setting up the subscription would be:

Create the subscription /entities/{code}/events.
Subscribe to the different events /subscription/{id}/subscribe
Activate the subscription with /enable

📘
Note that once the activation of the subscription is done, Wapping will start sending all the events to the provided endpoint.

Receiving Webhooks

Processing the webhooks require two steps. First validate the integrity of the message received, and secondly to process the message itself.

To validate the integrity of the message received via the webhook, it will be necessary to locate the signature and the timestamp. They are sent in the headers Wapping-Signature and Wapping-Timestamp, respectively

POST [https://my-endpoint.my-business.com/webhook](https://my-endpoint.my-business.com/webhook) HTTP/1.2

Content-Type: application/json

Wapping-Signature:

6107e5d13eb9c81ceb6705ba010d800e71204857a512739859d919be2852356e

Wapping-Timestamp: 1718175936

\{"entityCode":"NONE","eventCode":"NONE","entity":\{}}

Wapping-Timestamp is a Unix timestamp of the moment we send the webhook.

If too much time has passed since that moment, the webhook should be ignored to prevent replication attacks.

To verify the signature it will be necessary to calculate it. The signature is obtained using the HMACSHA256 algorithm. The secret key is the one specified when creating the webhook subscription, and the payload is obtained as follows:

\{timestamp}.\{webhook-body}

For this example

1718175936.\{"entityCode":"NONE","eventCode":"NONE","entity":\{}}

If the calculated signature does not match the one sent in the headers, the webhook should be ignored for security reasons.

The endpoint receiving the webhook must always return a successful HTTP response code, even if the message has been ignored. Otherwise, it will be counted as a failed delivery. A failed delivery will be retried up to 3 times at increasing time intervals, and then it will be marked as an delivery error.

The second part will be processing the event itself. The object received will be a JSON with the following structure:

{
    "id": 0, //Customer Id in Wapping
    "code": null, //Customer code 
    "name": "",
    "surname": "",
    "accountMobileNumber": "",
    "accountEmail": "",
    "urlImage": null,
    "languageCode": "es",
    "mobileValidated": true,
    "deleted": false,
    "address": {
        "description": null,
        "street": null,
        "region": null,
        "province": null,
        "number": 0,
        "postalCode": null,
        "city": null,
        "country": "UNKNOWN"
    },
    "thirdPartyIdentifiers": [ //Identifiers linked from third party systems (e.g Shopify, Custom, etc
        {
            "thirdPartySystemId": 0,
            "thirdPartyId": "",
            "customThirdPartyCode": null, //In case the systemId is Custom, the code will be defined
            "beginDate": "2025-01-01T00:00:00.000",
            "endDate": null
        }
    ]
}

With this implemented, remember to enable the subscription if it's not already done to allow the messages to be sent.