Webhook Management

On the webhooks page, you can manage webhook endpoints that will be called when certian events happen on the server.

Webhook response codes

Any status code other than 2xx will be considered an error

Validating payloads

With every payload, the X-Binja-Signature header will contain the hex digest of HMAC_SHA256(<webhook secret>, <request body>).

For example, to validate a payload in flask:

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-Hub-Signature required")

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

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

Payload format

Common fields

Key	Type	Description
event_id	string	Unique event identifier
event_type	string	Either create or delete
object_type	string	Type of object to which the event applies
data	object	Object containing data specific to the object_type

Data formats

Chat message

object_type
chat message

Key	Type	Description
project_file	string	ID of project file in which the message was sent
sender	string	Username of sender
message	string	Contents of message
timestamp	string	Timestamp of message (ISO 8601 format)

---

Project

object_type
project

Key	Type	Description
id	string	Unique project identifier
name	string	Project name
description	string	Project description
created	string	Date/time of project creation (ISO 8601 format)

---

Project file

object_type
project file

Key	Type	Description
id	string	Unique project file identifier
project	string	Unique identifier of project containing the project file
name	string	Project file name
description	string	Project file description
hash	string	Hash of project file contents
created	string	Date/time of project file creation (ISO 8601 format)

---

Snapshot

object_type
snapshot

Key	Type	Description
id	string	Unique snapshot identifier
project_file	string	Unique identifier of project file containing the snapshot
name	string	Project file name
author	string	Username of user that created the snapshot
created	string	Date/time of project file creation (ISO 8601 format)

---

Example payload

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