/ developers
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_urlmust be accessible from the public internet, meaning any localhost, private network domains, or domains that require authentication will all fail.
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.
There are two required headers in each request:
Content-Type: application/json
Authorization: Bearer <api_key>
The provided API Key is checked against any provided resource (where applicable) to confirm the appropriate permissions.
The Brandfolder Webhooks service allows for subscriptions to events within individual Brandfolders. The events that are currently supported are as follows:
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.
asset.create: A new asset has been created within the subscribed Brandfolder
asset.update: Asset data has been updated within the subscribed Brandfolder
asset.delete: An asset has been removed from within the subscribed Brandfolder
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.
Current qualifying events that trigger a Webhook are as follows:
Once a Webhook subscription as been created, the payload that will be sent to the user-provided
callback_urlafter an event has been triggered will have the following structure:
{
"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>"
}
}
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.
POST /api/v1/webhooks/send
Required Headers:
-H "Content-Type: application/json"
-H "Authorization: Bearer {BF_API_KEY}"
Required Payload (body/json):
{
"data": {
"attributes": {
"event_type": "<event_type>",
"resource_key": "<brandfolder_id>",
"resource_type": "brandfolder",
"callback_url": "<https url where webhook data will be POSTed>",
// OPTIONAL
"asset_key": "<asset id override>",
"organization_key": "<org id override>"
}
}
}
Potential Responses:
202: Webhook Successfully Created:
{
"message": "Added demo webhook to queue",
"status": "ok"
}
400: Invalid Payload Provided
403: Permission Denied for Provided Resource
404: Provided Resource Does Not Exist
409: Subscription Already Exists
Ensure that your code is able to receive a Brandfolder Webhook using this endpoint before creating a production Webhook subscription.
If you receive a 202 response at this endpoint, then a fake Webhook notification will POST to your callback_url. If you don't receive anything at your callback_url within a few minutes, it is likely that callback_url is invalid. Please ensure the URL begins with https:// and that it is a public domain (not localhost, behind a firewall, or any other domain requiring authentication) which can receive HTTP POST requests and respond with a 2xx HTTP status code.
Subscribe to get Webhook notifications for the specified asset event type within the specified Brandfolder.
POST /api/v1/webhooks
Required Headers:
-H "Content-Type: application/json"
-H "Authorization: Bearer {BF_API_KEY}"
Required Payload (body/json):
{
"data": {
"attributes": {
"event_type": "<event_type>",
"resource_key": "<brandfolder_id>",
"resource_type": "brandfolder",
"callback_url": "<https url where webhook data will be POSTed>"
}
}
}
Currently Supported Resource Types:
1. brandfolder
Currently Supported Event Types:
asset.create: A new asset has been created within the subscribed Brandfolder
asset.update: Asset data has been updated within the subscribed Brandfolder
asset.delete: An asset has been removed from within the subscribed Brandfolder
Potential Responses:
200: Webhook Successfully Created:
{
"data": {
"id": "<webhook_id>",
"attributes": {
"resource_key": "<brandfolder_id>",
"resource_type": "brandfolder",
"event_type": "<event_type>",
"callback_url": "<callback_url>"
}
}
}
400: Invalid Payload Provided
403: Permission Denied for Provided Resource
404: Provided Resource Does Not Exist
409: Subscription Already Exists
Will display data about all of the requester's owned Webhooks that are still active.
GET /api/v1/webhooks
Required Headers:
-H "Content-Type: application/json"
-H "Authorization: Bearer {BF_API_KEY}"
Potential Responses:
200: Will display all Webhooks associated with the provided API Key, or none if none exist.
{
"data": [
{
"id": <webhook_id>,
"attributes": {
"resource_key": <resource_key>,
"resource_type": <resource_type>,
"event_type": <event_type>,
"callback_url": <callback_url>
}
}
]
}
400: Invalid header provided
Will display data about the requested Webhook as long as it is still active.
GET /api/v1/webhooks/<webhook_id>
Required Headers:
-H "Content-Type: application/json"
-H "Authorization: Bearer {BF_API_KEY}"
Potential Responses:
200: Displays Webhook Details:
{
"data": {
"id": <webhook_id>,
"attributes": {
"resource_key": <resource_key>,
"resource_type": <resource_type>,
"event_type": <event_type>,
"callback_url": <callback_url>
}
}
}
400: Invalid Header Provided.
404: The Requested Webhook Does Not Exist.
Upon successful deletion, data will no longer be sent to the associated callback_url
DELETE /api/v1/webhooks/<webhook_id>
Required Headers:
-H "Content-Type: application/json"
-H "Authorization: Bearer {BF_API_KEY}"
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.