Source Code Webhooks

Webhooks enable your applications to receive real-time notifications when events occur in your source code repositories. This eliminates the need for polling and ensures your systems stay synchronized with code changes across all integrated platforms.

Unizo normalizes webhook events from GitHub, GitLab, Bitbucket, Azure DevOps, and other SCM connectors 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 Source Code webhooks. The list keeps growing as we add support for more events across different platforms.

Event Type	Description	Trigger Conditions
organization:renamed	Event broadcast when the organization's name was changed	Organization Renamed
organization:deleted	Event broadcast when an organization is disconnected	Organization Deleted
repository:created	Event broadcast when a new repository is created	Repository Created
repository:renamed	Event broadcast when a repository is renamed	Repository Renamed
repository:deleted	Event broadcast when a repository is deleted	Repository Deleted
branch:created	A new branch has been created	Branch creation from UI, API, or push
branch:deleted	A branch has been deleted	Branch deletion from UI, API, or after merge
commit:created	Event broadcast when a new commit is pushed to a branch	Commit Created

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

Parse the timestamp from the x-unizo-timestamp header and reject the request if it falls outside your tolerance window (recommended: 5 minutes).
Reconstruct the signed payload by concatenating the timestamp, a literal dot (.), and the raw request body.
Compute the expected signature using HMAC-SHA256 with your webhook signing secret as the key.
Strip the v1= prefix from the x-unizo-signature header to get the received signature.
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));

Organization Events

Organization Renamed

`organization:renamed`

Event broadcast when the organization's name was changed

POSThttps://api.yourapp.com/webhooks/unizo/scm

Headers

Name	Type	Required	Description
`x-unizo-event-type`	string	Yes	The type of event that was triggered
`x-unizo-signature`	string	Yes	HMAC-SHA256 signature, prefixed with v1=

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`contentType`	string	Yes	Branch name/identifier
`organization`	string	Yes	Organization name
`organization.id`	string	Yes	Organization ID
`organization.key`	string	Yes	Organization key
`organization.url`	string	Yes	Organization URL
`organization.from`	string	Yes	Source repository
`organization.to`	string	Yes	Target repository
`integration`	string	Yes	Integration name
`integration.type`	string	Yes	Integration type
`integration.id`	string	Yes	Integration ID
`integration.name`	string	Yes	Integration display name

Example Payload

{
  "type": "organization:renamed",
  "version": "1.0.0",
  "contentType": "application/json",
  "organization": {
    "id": "167400081",
    "key": "Bts-1tegrate-Org-update",
    "url": "https://api.github.com/orgs/Bts-1tegrate-Org-update",
    "from": "Bts-1tegrate-Org",
    "to": "Bts-1tegrate-Org-update"
  },
  "integration": {
    "type": "SCM",
    "id": "f8f0cc49-a656-4668-9d64-43cb2c8e5f90",
    "name": "Gi_Secu_1746454494408"
  }
}

Response

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

Organization Deleted

`organization:deleted`

Event broadcast when an organization is disconnected

POSThttps://api.yourapp.com/webhooks/unizo/scm

Headers

Name	Type	Required	Description
`x-unizo-event-type`	string	Yes	The type of event that was triggered
`x-unizo-signature`	string	Yes	HMAC-SHA256 signature, prefixed with v1=

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`contentType`	string	Yes	Branch name/identifier
`organization`	string	Yes	Organization name
`organization.id`	string	Yes	Organization ID
`organization.key`	string	Yes	Organization key
`integration`	string	Yes	Integration name
`integration.type`	string	Yes	Integration type
`integration.id`	string	Yes	Integration ID
`integration.name`	string	Yes	Integration display name

Example Payload

{
  "type": "organization:deleted",
  "version": "1.0.0",
  "contentType": "application/json",
  "organization": {
    "id": "210385971",
    "key": "webhookorgtest"
  },
  "integration": {
    "type": "SCM",
    "id": "c1686c58-90d0-4c00-b07b-92476beb9137",
    "name": "Gi_Secu_1746454781501"
  }
}

Response

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

Repository Events

Repository Created

`repository:created`

Event broadcast when a new repository is created

POSThttps://api.yourapp.com/webhooks/unizo/scm

Headers

Name	Type	Required	Description
`x-unizo-event-type`	string	Yes	The type of event that was triggered
`x-unizo-signature`	string	Yes	HMAC-SHA256 signature, prefixed with v1=

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`contentType`	string	Yes	Branch name/identifier
`repository`	string	Yes	Repository name
`repository.id`	string	Yes	Repository ID
`repository.key`	string	Yes	Repository key
`repository.state`	string	Yes	Repository state
`repository.createdDateTime`	string	Yes	Repository createdDateTime
`repository.url`	string	Yes	Repository url
`integration`	string	Yes	Integration name
`integration.type`	string	Yes	Integration type
`integration.id`	string	Yes	Integration ID
`integration.name`	string	Yes	Integration display name

Example Payload

{
  "type": "repository:created",
  "version": "1.0.0",
  "contentType": "application/json",
  "repository": {
    "id": "repo-enterprise-sec-9971",
    "key": "cloud-compliance-engine",
    "state": "active",
    "summary": "Infrastructure-as-Code (IaC) policies and scanning tools for cloud compliance",
    "createdDateTime": "2025-05-05T18:20:45Z",
    "url": "https://git.unizo.io/enterprise/cloud-compliance-engine"
  },
  "integration": {
    "type": "SCM",
    "id": "0c92e542-fb3e-4027-98c4-7235a691b997",
    "name": "Bitbucket-SecOps"
  }
}

Response

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

Repository Renamed

`repository:renamed`

Event broadcast when a new repository is renamed

POSThttps://api.yourapp.com/webhooks/unizo/scm

Headers

Name	Type	Required	Description
`x-unizo-event-type`	string	Yes	The type of event that was triggered
`x-unizo-signature`	string	Yes	HMAC-SHA256 signature, prefixed with v1=

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`contentType`	string	Yes	Branch name/identifier
`repository`	string	Yes	Repository name
`repository.id`	string	Yes	Repository ID
`repository.key`	string	Yes	Repository key
`repository.createdDateTime`	string	Yes	Repository createdDateTime
`repository.from`	string	Yes	Source Repository Name
`repository.to`	string	Yes	Target Repository Name
`integration`	string	Yes	Integration name
`integration.type`	string	Yes	Integration type
`integration.id`	string	Yes	Integration ID
`integration.name`	string	Yes	Integration display name

Example Payload

{
  "type": "repository:renamed",
  "version": "1.0.0",
  "contentType": "application/json",
  "repository": {
    "id": "978118703",
    "key": "Demo-testing",
    "createdDateTime": "2025-05-05T13:59:18Z",
    "from": "Demo-testing1",
    "to": "Demo-testing"
  },
  "integration": {
    "type": "SCM",
    "id": "14616a42-2a4a-42b2-b167-030908d6fc17",
    "name": "Gi_Secu_1746452195518"
  }
}

Response

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

Repository Deleted

`repository:deleted`

Event broadcast when a new repository is renamed

POSThttps://api.yourapp.com/webhooks/unizo/scm

Headers

Name	Type	Required	Description
`x-unizo-event-type`	string	Yes	The type of event that was triggered
`x-unizo-signature`	string	Yes	HMAC-SHA256 signature, prefixed with v1=

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`contentType`	string	Yes	Branch name/identifier
`repository`	string	Yes	Repository name
`repository.id`	string	Yes	Repository ID
`repository.key`	string	Yes	Repository key
`repository.createdDateTime`	string	Yes	Repository createdDateTime
`integration`	string	Yes	Integration name
`integration.type`	string	Yes	Integration type
`integration.id`	string	Yes	Integration ID
`integration.name`	string	Yes	Integration display name

Example Payload

{
  "type": "repository:deleted",
  "version": "1.0.0",
  "contentType": "application/json",
  "repository": {
    "id": "978118703",
    "key": "Demo-testing",
    "createdDateTime": "2025-05-05T14:00:17Z"
  },
  "integration": {
    "type": "SCM",
    "id": "14616a42-2a4a-42b2-b167-030908d6fc17",
    "name": "Gi_Secu_1746452195518"
  }
}

Response

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

Branch Events

Branch Created

`branch:created`

Triggered when a new branch is created in a repository

POSThttps://api.yourapp.com/webhooks/unizo/scm

Headers

Name	Type	Required	Description
`x-unizo-event-type`	string	Yes	The type of event that was triggered
`x-unizo-signature`	string	Yes	HMAC-SHA256 signature, prefixed with v1=

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`contentType`	string	Yes	Branch name/identifier
`branch`	string	Yes	Branch name/identifier
`branch.id`	string	Yes	Branch Id
`branch.key`	string	Yes	Branch Key
`integration`	string	Yes	Integration name
`integration.type`	string	Yes	Integration type
`integration.id`	string	Yes	Integration id
`integration.name`	string	Yes	Integration display name

Example Payload

{
  "type": "branch:created",
  "version": "1.0.0",
  "contentType": "application/json",
  "branch": {
    "id": "Shruthi089-patch-1",
    "key": "Shruthi089-patch-1"
  },
  "integration": {
    "type": "SCM",
    "id": "14616a42-2a4a-42b2-b167-030908d6fc17",
    "name": "Gi_Secu_1746452195518"
  }
}

Response

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

Branch Deleted

`branch:deleted`

Triggered when a branch is deleted from a repository

POSThttps://api.yourapp.com/webhooks/unizo/scm

Headers

Name	Type	Required	Description
`x-unizo-event-type`	string	Yes	The type of event that was triggered
`x-unizo-signature`	string	Yes	HMAC-SHA256 signature, prefixed with v1=

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`contentType`	string	Yes	Branch name/identifier
`branch`	string	Yes	Branch name/identifier
`branch.id`	string	Yes	Branch Id
`branch.key`	string	Yes	Branch Key
`integration`	string	Yes	Integration name
`integration.type`	string	Yes	Integration type
`integration.id`	string	Yes	Integration id
`integration.name`	string	Yes	Integration display name

Example Payload

{
  "type": "branch:deleted",
  "version": "1.0.0",
  "contentType": "application/json",
  "branch": {
    "id": "Testingdelete",
    "key": "Testingdelete"
  },
  "integration": {
    "type": "SCM",
    "id": "14616a42-2a4a-42b2-b167-030908d6fc17",
    "name": "Gi_Secu_1746452195518"
  }
}

Response

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

Commit Events

Commit Created

`commit:created`

Event broadcast when a new commit is pushed to a branch

POSThttps://api.yourapp.com/webhooks/unizo/scm

Headers

Name	Type	Required	Description
`x-unizo-event-type`	string	Yes	The type of event that was triggered
`x-unizo-signature`	string	Yes	HMAC-SHA256 signature, prefixed with v1=

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`contentType`	string	Yes	Branch name/identifier
`commit`	string	Yes	Array of commit objects
`commit.id`	string	Yes	Commit Id
`commit.message`	string	Yes	Commit message
`commit.author`	string	Yes	Commit author details
`commit.author.name`	string	Yes	Author name
`commit.author.email`	string	Yes	Author email
`committer`	string	Yes	Committer
`committer.name`	string	Yes	Committer name
`committer.email`	string	Yes	Committer email
`createdDateTime`	string	Yes	Committer created Timestamp
`url`	string	Yes	URL
`repository`	string	Yes	Repository name
`repository.id`	string	Yes	Repository ID
`repository.key`	string	Yes	Repository key
`repository.url`	string	Yes	Repository url
`branch`	string	Yes	Branch name/identifier
`branch.id`	string	Yes	Branch Id
`branch.key`	string	Yes	Branch Key
`integration`	string	Yes	Integration name
`integration.type`	string	Yes	Integration type
`integration.id`	string	Yes	Integration id
`integration.name`	string	Yes	Integration display name

Example Payload

{
  "type": "commit:created",
  "version": "1.0.0",
  "contentType": "application/json",
  "commit": {
    "id": "a1b2c3d4e5f6g7h8i9j0k1!@#",
    "message": "Add new feature: User authentication",
    "author": {
      "name": "John Doe",
      "email": "[email protected]"
    },
    "committer": {
      "name": "Jane Smith",
      "email": "[email protected]"
    },
    "createdDateTime": "2025-05-05T15:30:00Z",
    "url": "https://git.unizo.io/enterprise/cloud-compliance-engine/commit/a1b2c3d4e5f6g7h8i9j0k1!@#"
  },
  "repository": {
    "id": "repo-enterprise-sec-9971",
    "key": "cloud-compliance-engine",
    "url": "https://git.unizo.io/enterprise/cloud-compliance-engine"
  },
  "branch": {
    "id": "main",
    "key": "main"
  },
  "integration": {
    "type": "SCM",
    "id": "0c92e542-fb3e-4027-98c4-7235a691b997",
    "name": "Bitbucket-SecOps"
  }
}

Response

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

Webhook Delivery & Retries

Unizo implements automatic retry logic for failed webhook deliveries:

Initial Delivery: Immediate
First Retry: After 1 minute
Second Retry: After 5 minutes
Third Retry: After 15 minutes
Final Retry: After 1 hour

Webhooks are considered failed if:

Your endpoint returns a non-2xx status code
Connection timeout (30 seconds)
SSL/TLS errors

Best Practices

1. Idempotency

Idempotent Webhook Handler

async function handleWebhook(request) {
const deliveryId = request.headers['x-unizo-delivery-id'];

// Check if already processed
if (await isProcessed(deliveryId)) {
  return { status: 200, message: 'Already processed' };
}

// Process webhook
await processWebhook(request.body);

// Mark as processed
await markProcessed(deliveryId);

return { status: 200 };
}

2. Async Processing

Asynchronous Processing

app.post('/webhooks/scm', (req, res) => {
// Validate signature
if (!verifySignature(req)) {
  return res.status(401).send('Invalid signature');
}

// Queue for processing
webhookQueue.add(req.body);

// Return immediately
res.status(200).send('OK');
});

3. Error Handling

Comprehensive Error Handling

async function processWebhook(payload) {
try {
  switch (payload.type) {
    case 'branch:created':
      await handleBranchCreated(payload);
      break;
    case 'pull_request:merged':
      await handlePullRequestMerged(payload);
      break;
    default:
      logger.warn(`Unknown webhook type: ${payload.type}`);
  }
} catch (error) {
  logger.error('Webhook processing failed', {
    error: error.message,
    payload,
    stack: error.stack
  });
  throw error;
}
}

Need Help?

For webhook-related support:

Contact support at [email protected]

Supported Event Types​

Webhook Security

Security Headers

Signature Verification

Verification Steps

Reference Implementation

Organization Events​

Organization Renamed

organization:renamed

Headers

Request Body Schema

Example Payload

Response

Organization Deleted

organization:deleted

Headers

Request Body Schema

Example Payload

Response

Repository Events​

Repository Created

repository:created

Headers

Request Body Schema

Example Payload

Response

Repository Renamed

repository:renamed

Headers

Request Body Schema

Example Payload

Response

Repository Deleted

repository:deleted

Headers

Request Body Schema

Example Payload

Response

Branch Events​

Branch Created

branch:created

Headers

Request Body Schema

Example Payload

Response

Branch Deleted

branch:deleted

Headers

Request Body Schema

Example Payload

Response

Commit Events​

Commit Created

commit:created

Headers

Request Body Schema

Example Payload

Response

Webhook Delivery & Retries​

Best Practices​

1. Idempotency​

Idempotent Webhook Handler

2. Async Processing​

Asynchronous Processing

3. Error Handling​

Comprehensive Error Handling

Need Help?​

Supported Event Types

Organization Events

`organization:renamed`

`organization:deleted`

Repository Events

`repository:created`

`repository:renamed`

`repository:deleted`

Branch Events

`branch:created`

`branch:deleted`

Commit Events

`commit:created`

Webhook Delivery & Retries

Best Practices

1. Idempotency

2. Async Processing

3. Error Handling

Need Help?