Skip to main content

Getting Started

What are webhooks?#

Webhooks allow you to get programmatical notifications from Tribe about changes to your data as they happen. If you're new to webhooks, read this guide to learn more.

Rather than requiring you to pull information via our API, webhooks will push information to your endpoint. When one of those events is triggered (for example a new post is created), Tribe will send this notification as an HTTP POST request, with a JSON body, to the endpoint you specify.

Enabling webhooks#

To enable webhooks, you should go to the "Webhooks" section of your app under Tribe developer portal and enter a webhook URL.

note

Don't have an app yet? Follow the instructions here.

Webhooks

Saving webhook URL#

Saving the webhook URL is only possible if you pass the challenge. This is to ensure your webhook URL is set up properly.

To do so, enter a URL and click on "Send test request". Tribe will send an HTTP POST request to the provided URL with a payload similar to bellow:

{
"networkId": "CAxOmI7I7X",
"context": "NETWORK",
"currentSettings": [],
"type": "TEST",
"data": {
"challenge": "d77dae12ea612cf647d6e2e78dd2b7470e4e4358"
}
}

To pass the test challenge, you should send back a JSON response as followed:

HTTP 200 OK
Content-type: application/json
{
"type": "TEST",
"status": "SUCCEEDED",
"data": {
"challenge": "d77dae12ea612cf647d6e2e78dd2b7470e4e4358"
}
}

Please note that the response must include the type and status as well as the same exact challenge received in the original request from Tribe. If the response is correct, you will receive a success toast and you can simply click on "Update" to save the webhook URL.

Adding webhook subscriptions#

In most cases, you don't want to get notified on every action in Tribe. As an example, you may be interested in "Creation of posts" and "Deletion of posts" and "Reactions on posts".

You can pick what events you're interested in by picking community events under "Webhook supscriptions" section.

Webhook requests structure#

Every webhook request sent by Tribe follows the below structure:

{
"networkId": "CAxOmI7I7t", // The community ID
"context": "NETWORK", // The context of the action
"entityId": "CAxOmI7I7t", // The ID of the context
"currentSettings": [],
"type": "SUBSCRIPTION", // The type of webhook request
"data": {
"time": "2021-12-20T02:32:06.721Z",
"name": "space.created",
"noun": "SPACE",
"shortDescription": "Create Space",
"verb": "CREATED",
"actor": { // The member or entity that performed the action
"id": "olQ88vTqYp",
"roleId": "Kni0OF7HtE",
"roleType": "admin",
},
"object": { // The main object involved in the action
"id": "ky4X0Ci6q4M5",
// ...
},
"target": { // The ID of the target and all relevant objects
"networkId": "CAxOmI7I7t",
// ...
},
"id": "8147a2af79248c3c8815ffeaa6777a7f", // Unique ID for this webhook event instance
}

In most cases, you want to make sure the type of the webhook request is SUBSCRIPTION and have a switch case based on the name or noun+verb.

Verifying webhook requests#

Every single Tribe webhook request includes X-Tribe-Signature headers. We highly recommend verifying all webhook requests by comparing the X-Tribe-Signature with the "Signing secret" provided under "Credentials" section of your app in the Tribe developers portal.

note

Not verifying X-Tribe-Signature will let third parties misuse your webhook endpoint by faking POST requests and can be dangerous.

Preventing replays#

Tribe does not ensure that an event will be triggered just once. As an example, Tribe will retry an event if it times out.

Every single Tribe webhook request includes X-Tribe-Request-Timestamp and a unique data.id.

To ensure that an event is handled only once on your side, we recommend checking data.id and making sure you haven't processed an event with that unique ID before. We also recommend checking X-Tribe-Request-Timestamp and ignore any events older than 15 minutes before the request timestamp.

Doing so will also prevent replay attacks on your endpoints in case it happens.