MENU

BETA: Webhooks

Overview

This service is currently in BETA. If you encounter any errors, email us at api@brandfolder.com.

The Brandfolder webhooks service will send asset data to the user-provided callback_url at the time the subscribed event occurs within the Brandfolder system.

Authentication

Authentication is performed with every API call by sending a header with your unique Brandfolder API key.

The required header in each request is:

Authorization: Bearer {BF_API_KEY}

Each response to your API calls will only include the resources that you (or the User whose API key your application is using) can access based on your permissions.

Service Details

Webhook payload POST'ed to the user-provided callback_url:

    {
        "data": {
            "attributes": {
                "key": <unique_asset_identifier>,
                "event_time": <timestamp when event occured in Brandfolder>,
                "event_type": <the event type that triggered the webhook>,
                "brandfolder_key": <unique_brandfolder_identifier>,
                "organization_key": <unique_organization_identifier>
            },
            "webhook_id": <webhook_id>
    }

Supported event_type's

"asset.create": A new asset has been created within the subscribed Brandfolder
"asset.update": Asset data has been updated (e.g. name change, tags changed, etc.)
"asset.delete": An asset has been removed from the subscribed Brandfolder

The Brandfolder Webhook Service allows for subscriptions for events within individual Brandfolders.

Due to the way Brandfolder manages assets, you will see both an "asset.create" event and an "asset.update" event upon creation of a new asset. An asset.create event is triggered when Brandfolder recognizes the new asset and begins to process it for use. An asset.update event is then triggered when the asset is ready for use.

Permissions will be validated for each event that has an associated webhook. If it is determined that the API key associated with a webhook no longer has access to the associated resource, the webhook will be immediately disabled. In order to make the most efficient use of available resources, this API key validation may be cached for a period of time. The maximum potential delay of permissions being up to date is 30 minutes.

Making Requests

All webhooks requests are made via the following URL:

https://brandfolder.com + resource endpoint

When using our examples in your code, you'll need to make sure to replace <resource_key> (or any other variable like <event_type>) with the actual value to be used.

Actions

Create a Webhook

Required payload (body/json)

    {
    "data": {
        "attributes": {
            "event_type": <event_type>,
            "resource_key": <brandfolder_key>,
            "resource_type": <resource_type>,
            "callback_url": <https url where webhook data will be POSTed>
        }
    }

Example JSON Response

    {
        "data": {
            "id": <webhook_id>,
            "attributes": {
                "resource_key": <resource_key>,
                "resource_type": <resource_type>,
                "event_type": <event_type>,
                "callback_url": <callback_url>
             }
        }
    }

POST /api/v1/webhooks

Creating a webhook will generate a subscription to the resource (e.g. Brandfolder) provided for the event type (e.g. asset.create) provided.

Currently Supported Resource Types:

  1. brandfolder

Potential Responses:

200: Webhook Successfully Created:

400: Invalid Payload Provided

403: Permission Denied for Provided Resource

404: Provided Resource Does Not Exist

409: Subscription Already Exists

List Active Webhooks

Example JSON Response

        {
            "data": [
                {
                "id": <webhook_id>,
                "attributes": {
                    "resource_key": <resource_key>,
                    "resource_type": <resource_type>,
                    "event_type": <event_type>,
                    "callback_url": <callback_url>
                 }
            ]
        }

GET /api/v1/webhooks

Lists data about all of the requester's owned webhooks that are still active.

Potential Responses:

200: Will display all webhooks associated with the provided API Key, or none if none exist.

400: Invalid header provided.

Fetch Webhook Data

Example JSON Response

        {
            "data": {
                "id": <webhook_id>,
                "attributes": {
                    "resource_key": <resource_key>,
                    "resource_type": <resource_type>,
                    "event_type": <event_type>,
                    "callback_url": <callback_url>
                 }
            }
        }

GET /api/v1/webhooks/<webhook_id>

Displays data about the requested webhook, assuming it is still active.

Potential Responses:

200: Displays webhook details.

400: Invalid header provided.

404: The requested webhook does not exist.

Delete a Webhook

DELETE /api/v1/webhooks/<webhook_id>

Upon successful deletion, data will no longer be sent to the associated callback_url

Potential Responses:

200: Webhook successfully deleted.

400: Invalid header provided.

404: Could not determine this webhook exists or the requester does not own the webhook.