File Storage Webhooks

Webhooks enable your applications to receive real-time notifications when events occur in your file Storage and issue tracking systems. This eliminates the need for polling and ensures your systems stay synchronized with ticket updates, status changes, comments, and attachment activities across all integrated platforms.

Unizo normalizes webhook events from Jira, ServiceNow, Zendesk, GitHub Issues, and other file Storage providers into a consistent format. This means you write your webhook handler once and it works with all supported platforms.

Webhook Configuration

To set up webhooks for your integration, visit the Unizo Console Webhooks section for step-by-step configuration guide.

Supported Event Types

These are the event types currently supported by Unizo's File Storage webhooks. The list keeps growing as we add support for more events across different platforms.

Event Type	Description	Trigger Conditions
file:created	A new file has been created	File creation via UI, API, email, or automation
file:updated	File information has been modified	Title, description, status, priority, or assignee changes
file:deleted	A file has been deleted	File deletion or permanent removal

Webhook Security

Every webhook request sent by Unizo includes a cryptographic signature so you can verify that the payload is authentic and has not been tampered with.

Security Headers

Header	Description
x-unizo-event-type	The type of event that triggered the webhook
x-unizo-signature	HMAC-SHA256 signature of the payload, prefixed with v1= (e.g., v1=ee084789...)
x-unizo-timestamp	Unix epoch timestamp (seconds) when the request was signed
x-unizo-delivery-id	Unique identifier for this webhook delivery

Signature Verification

The signed payload is constructed by joining the timestamp and the raw request body with a dot separator: {timestamp}.{payload}. This ensures the timestamp is covered by the signature, preventing replay attacks.

Verification Steps

1. Parse the timestamp from the x-unizo-timestamp header and reject the request if it falls outside your tolerance window (recommended: 5 minutes).
2. Reconstruct the signed payload by concatenating the timestamp, a literal dot (.), and the raw request body.
3. Compute the expected signature using HMAC-SHA256 with your webhook signing secret as the key.
4. Strip the v1= prefix from the x-unizo-signature header to get the received signature.
5. Compare the two signatures using a constant-time comparison function to prevent timing attacks.

Reference Implementation

const crypto = require("crypto");

function verifyWebhookSignature(
  payload,
  signatureHeader,
  timestampHeader,
  secret,
  toleranceSeconds = 300
) {
  // 1. Reject stale timestamps to prevent replay attacks
  const now = Math.floor(Date.now() / 1000);
  const timestamp = parseInt(timestampHeader, 10);

  if (Number.isNaN(timestamp)) {
    return false;
  }

  if (Math.abs(now - timestamp) > toleranceSeconds) {
    return false;
  }

  // 2. Reconstruct the signed payload: "{timestamp}.{payload}"
  const signedPayload = `${timestamp}.${payload}`;

  // 3. Compute the expected signature
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");

  // 4. Strip the "v1=" prefix from the received signature
  const received = signatureHeader.startsWith("v1=")
    ? signatureHeader.slice(3)
    : signatureHeader;

  // 5. Constant-time comparison to prevent timing attacks
  try {
    return crypto.timingSafeEqual(
      Buffer.from(expected, "hex"),
      Buffer.from(received, "hex")
    );
  } catch {
    return false;
  }
}

// Usage
const isValid = verifyWebhookSignature(
  rawBody,                                // raw request body string
  headers["x-unizo-signature"],           // "v1=ee084789..."
  headers["x-unizo-timestamp"],           // "1774093147"
  process.env.UNIZO_WEBHOOK_SECRET        // your signing secret
);

if (!isValid) {
  return res.status(401).json({ error: "Invalid signature" });
}

// Signature verified — process the event
handleEvent(JSON.parse(rawBody));

File Events

File Created

file:created

Triggered when a new file is created in the file Storage system

POSThttps://api.yourapp.com/webhooks/unizo/file Storage

Headers

Name	Type	Required	Description
x-unizo-event-type	string	Yes	Event type: file:created
x-unizo-signature	string	Yes	HMAC-SHA256 signature, prefixed with v1=

Request Body Schema

Property	Type	Required	Description

Example Payload

{
  "type": "file:created",
  "version": "1.0.0",
  "contentType": "application/json",
  "file": {
    "id": "10099",
    "name": "NewProject"
  },
  "integration": {
    "type": "FILE_STORAGE",
    "id": "f2ae41b8-6aa9-434b-84ab-ddc0a7321351",
    "name": "Ji_Secu_1756452472351"
  }
}

Response

200 OK	Webhook processed successfully
400 Bad Request	Invalid webhook payload
401 Unauthorized	Invalid or missing signature

File Updated

file:updated

Triggered when file information is modified

POSThttps://api.yourapp.com/webhooks/unizo/file Storage

Headers

Name	Type	Required	Description
x-unizo-event-type	string	Yes	Event type: file:created
x-unizo-signature	string	Yes	HMAC-SHA256 signature, prefixed with v1=

Request Body Schema

Property	Type	Required	Description

Example Payload

{
  "type": "file:updated",
  "version": "1.0.0",
  "contentType": "application/json",
  "file": {
    "id": "10099",
    "name": "NewProject"
  },
  "integration": {
    "type": "FILE_STORAGE",
    "id": "f2ae41b8-6aa9-434b-84ab-ddc0a7321351",
    "name": "Ji_Secu_1756452472351"
  }
}

Response

200 OK	Webhook processed successfully
400 Bad Request	Invalid webhook payload
401 Unauthorized	Invalid or missing signature

File Deleted

file:deleted

Triggered when a file is deleted from the file Storage system

POSThttps://api.yourapp.com/webhooks/unizo/file Storage

Headers

Name	Type	Required	Description
x-unizo-event-type	string	Yes	Event type: file:created
x-unizo-signature	string	Yes	HMAC-SHA256 signature, prefixed with v1=

Request Body Schema

Property	Type	Required	Description

Example Payload

{
  "type": "file:deleted",
  "version": "1.0.0",
  "contentType": "application/json",
  "file": {
    "id": "10099",
    "name": "NewProject"
  },
  "integration": {
    "type": "FILE_STORAGE",
    "id": "f2ae41b8-6aa9-434b-84ab-ddc0a7321351",
    "name": "Ji_Secu_1756452472351"
  }
}

Response

200 OK	Webhook processed successfully
400 Bad Request	Invalid webhook payload
401 Unauthorized	Invalid or missing signature

Need Help?

For webhook-related support:

• Contact support at [email protected]