Admin Interface: Webhooks

Use the Webhooks page to deliver outbound notifications when projects, files, snapshots, or chat messages are created or deleted.

Creating or Modifying a Webhook

1. Set the URL and Secret (used for request signing).
2. Choose a Format type (Generic JSON or Slack).
3. Select one or more Actions (pre-seeded create/delete events for chat messages, snapshots, projects, and project files).
4. Scope delivery with include/exclude filters (projects, project groups, groups, users).
5. Save.

Filtering rules

• Excludes always win over includes.
• If you set an include filter and the event lacks that context (e.g., no actor for a system event), the event is skipped.
• Included project groups limits delivery to projects that those groups can access.
• Included/Excluded groups and Included/Excluded users require an actor; events without an actor are skipped when these filters are set.

Webhook requests time out after WEBHOOK_TIMEOUT seconds (configure under Config).

Delivery History

When editing an existing webhook, the form shows the last 20 requests with status icons. Expand an entry to view request/response headers, bodies, and any error messages. Use this for debugging and verification.

Validating Payloads

Every request includes X-Binja-Signature: HMAC_SHA256(<secret>, <request body>), if you need to verify payloads. Here's an example of doing this in a Flask application:

import hmac

from flask import Flask, request, abort

app = Flask(__name__)

@app.route("/", methods=['POST'])
def validate_webhook():
    expected = request.headers.get("X-Binja-Signature")
    if not expected:
        abort(400, "X-Binja-Signature required")

    digest = hmac.new(b"<webhook secret>", request.data, "sha256").hexdigest()

    if not hmac.compare_digest(expected, digest):
        abort(400, "Invalid signature")
    return ""

Payload Formats

At present, we support two different types of payload formats: A generic JSON format and a Slack-specific format that conforms to that platform's expectations. Contact us if there's another platform you'd like us to add explicit support for.

Generic JSON (default)

Common envelope fields:

Key	Type	Description
event_id	string	Unique event identifier
event_type	string	create or delete
object_type	string	Object type (project, project file, snapshot, chat message)
project	string	Project ID, when the event is associated with a project
actor	string	Display name or username of the actor, when available
data	object	Object-specific payload

Object-specific data:

Chat message (object_type: chat message)

Key	Type	Description
project_file	string	Project file ID
sender	string	Username of sender
message	string	Message contents
timestamp	string	ISO 8601 timestamp

Project (object_type: project)

Key	Type	Description
id	string	Project ID
name	string	Project name
description	string	Project description
created	string	ISO 8601 creation time

Project file (object_type: project file)

Key	Type	Description
id	string	Project file ID
project	string	Parent project ID
name	string	File name
description	string	File description
hash	string	SHA-256 hash of the uploaded file
created	string	ISO 8601 creation time

Snapshot (object_type: snapshot)

Key	Type	Description
id	string	Snapshot ID
project_file	string	Parent project file ID
project_file_name	string	Parent project file name
name	string	Snapshot comment/name
author	string	Username of the author
created	string	ISO 8601 creation time

Slack

format_type = Slack reshapes the payload into a Slack-compatible message with a short summary and an attachment containing the same data. The request is still signed with X-Binja-Signature.

Example payload

{
  "event_id": "6ce49d59-1dc6-49fa-a987-4a46b789ae3f",
  "event_type": "create",
  "object_type": "project",
  "project": "3864aa48-85e9-4781-b8fc-d66c409de0ed",
  "actor": "admin",
  "data": {
    "created": "2022-05-03T20:54:34.050Z",
    "description": "A new project",
    "id": "3864aa48-85e9-4781-b8fc-d66c409de0ed",
    "name": "New project"
  }
}