Webhooks allow you to build or set up integrations which subscribe to certain events on the Mapp DMP. When one of those events is triggered, we’ll send a HTTP POST payload (JSON, see below) to the webhook’s configured URL. Webhooks can be used to update an external system. You’re only limited by your imagination.

Contents on this page

GET /api/webhook

Description

List your webhooks

Endpoint

/api/webhook

Method

GET

The following query parameters can be used:

Parameters	Description
id	Optional. Place a custom data source ID here to get a single result.

POST /api/webhook

Decription

Create a webhook

Endpoint

/api/webhook

Method

POST

The following parameters can be used:

Parameters	Description
url	A full URL to the endpoint you want us to call (supports both HTTPS and HTTP)
secret	A secret string used for generating the message signature (maximum length 255 characters)

PUT /api/webhook?id=123

Decription

Update a webhook

Endpoint

/api/webhook?id=123

Method

PUT

The following parameters can be used:

Parameters	Description
url	A full URL to the endpoint you want us to call (supports both HTTPS and HTTP)
secret	A secret string used for generating the message signature (maximum length 255 characters)

DELETE /api/webhook?id=123

Decription

Delete a webhook

Endpoint

/api/webhook?id=123

Method

DELETE

Changes to webhooks

It can take up to 10 minutes for changes to become active in the webhooks. This means that after creation it might take up to 10 minutes before seeing the first events being delivered. The same applies for modifications and removal of the webhooks.

Authentication

We recommend the use of basic authentication in your URL to protect it from external access. For example:

https://username:password@api.your-domain.com/webhook

Message signatures

To ensure the messages come from Mapp we recommend to use an Authentication mechanism. In addition we will send a message signature for each individual call to your webhook.

The message signature is a SHA1 hexadecimal hash of the JSON message + the secret provided.

Java example with Apache digest utils library

String signature = DigestUtils.shaHex(jsonStr + secretStr);

This signature is delivered in the X-Signature header.

We recommend you to generate your own signature (based on your knowledge of the secret, and the received JSON message) and check that with the one that is delivered through the header. This will prevent malicious third parties from modifying the contents of any messages.

Example payload

{
    "event": "OBJECT_UPDATE",
    "audit": {
        "environment": "production",
        "user_id": "123",
        "primary_user_groups": [
            "987"
        ],
        "cluster_id": "234",
        "customer_id": "12345",
        "timestamp": 1429772938,
        "event_id": "74887dd7-4a9e-4e0b-bd69-6bc27c832d84"
    },
    "object": {
        "type": "Audiences",
        "primary_keys": {
            "id": "457882"
        },
        "changes": {
            "status": "UP",
			"size": 110923
        }
    }
}

Browser not supported