# Webhooks

The Brandfolder Webhooks service allows you to subscribe to event-based notifications (callbacks) when a qualifying event is triggered within Brandfolder. Asset data will then be sent to the user-provided `callback_url` at the time the subscribed event occurs within the specified Brandfolder. 

> NOTE: The `callback_url` must be accessible from the public internet, meaning any localhost, private network domains, or domains that require authentication will all fail.

<h2>Authentication</h2>

Utilizing Webhooks requires authentication with the resource (Brandfolder) being subscribed to. A user's unique API Key is required in a header for actions on all endpoints related to the Webhooks service.

- Find your API key at <a href="https://brandfolder.com/profile#integrations" target="_blank">https://brandfolder.com/profile#integrations</a>.
- Click the icon to the right of your key to copy it to your clipboard.

There are two required headers in each request: 

`Content-Type: application/json` <br>
`Authorization:  Bearer <api_key>`

The provided API Key is checked against any provided resource (where applicable) to confirm the appropriate permissions.
___

<h2>Service Details</h2>

The Brandfolder Webhooks service allows for subscriptions to events within individual Brandfolders. 

> NOTE: Asset data updates made at the Collection level will trigger a Brandfolder Webhook subscription. Since assets live at the Brandfolder level, any updates made at the Collection level would be reflected on the Brandfolder level as well, thus triggering a Webhook.

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. A `create` event is triggered when Brandfolder recognizes the new asset and begins to process it for use. An `update` event is triggered when the asset is ready for use.

The following event types trigger webhooks:

* `asset.create` - Asset creation. A new asset has been added to a subscribed Brandfolder.
* `asset.update` - Asset update. Asset data has been updated within a subscribed Brandfolder. One or more of the following asset attributes has been updated:
    * Name
    * Description
    * Section
    * Approval status
    * Expiration status
    * Comments & Annotations
        * Adding / Updating
        * Deleting
    * Tags
        * Adding / Updating
        * Deleting
    * Custom Fields
        * Adding / Updating
        * Deleting
* `asset.delete` - Asset deletion. An asset has been removed from within a subscribed Brandfolder.

> Once a Webhook subscription as been created, the payload that will be sent to the user-provided `callback_url` after an event has been triggered will have the following structure:

```json
{
    "data": {
        "attributes": {
            "key": "<unique_asset_identifier>",
            "event_time": "<event occurance timestamp in format YYYY-MM-DD HH:MM:SS.000000 with six decimal place microsecond precision>",
            "event_type": "<the event type that triggered the webhook>",
            "brandfolder_key": "<unique_brandfolder_identifier>",
            "organization_key": "<unique_organization_identifier>"
        },
        "webhook_id": "<webhook_id>"
    }
}
```

> NOTE: The callback payload is a "skinny" payload -- it indicates which assets changed and the type of event that occurred, but does not contain any data from the assets themselves.

The Brandfolder Webhook service requires your application to immediately acknowledge receipt of any Webhooks by returning a `2xx` HTTP status code. If Brandfolder does not receive an acknowledgement or any non `2xx` HTTP status code is returned, Brandfolder will retry the Webhook up to 15 times with exponentially increasing wait times in between. 

**Any Webhook subscriptions that continue to fail without remedy will be made inactive.**

Messages may be sent out of order to the `callback_url` associated with a Webhook subscription. The `event_time` provided in the payload can be used to order events.

If the API Key associated with a Webhook subscription loses access to the associated resource, the subscription will be deactivated within 30 minutes.