Platform Webhooks

Platform webhooks enable your applications to receive real-time notifications when integration lifecycle events occur in Unizo.
They help you stay synchronized with configuration changes and automate downstream updates without polling.

Unizo sends webhook notifications for key integration events such as creation, update, and deletion—standardized across all connected systems.

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 Platform Webhooks.
Each event delivers normalized metadata so that your webhook handlers can process events uniformly.

Event Type	Description	Trigger Conditions
integration:created	Triggered when a new integration is successfully created in Unizo.	Integration Created
integration:updated	Triggered when an existing integration configuration is updated.	Integration Updated
integration:deleted	Triggered when an integration is disconnected or removed from Unizo.	Integration Deleted

Webhook Security

All webhooks from Unizo include security headers to verify authenticity:

Headers

Header	Description
x-unizo-event-type	The type of event that triggered the webhook
x-unizo-signature	HMAC SHA-256 signature for request validation
x-unizo-timestamp	Unix timestamp when the event was sent
x-unizo-delivery-id	Unique identifier for this webhook delivery

Signature Verification

Verify the authenticity of incoming webhooks using HMAC SHA-256:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

Integration Events

Integration Created

integration:created

Triggered when a new integration is created and connected in Unizo.

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

Headers

Name	Type	Required	Description
x-unizo-event-type	string	Yes	Type of event triggered
x-unizo-signature	string	Yes	HMAC SHA-256 signature for payload verification

Request Body Schema

Property	Type	Required	Description
type	string	Yes	Event type identifier
version	string	Yes	Webhook payload version
contentType	string	Yes	Content type of the webhook payload
integration.id	string	Yes	Unique identifier for the integration
integration.name	string	Yes	Display name of the integration
integration.type	string	Yes	Integration category, e.g., SCM, HRIS, ITSM
integration.status	string	Yes	Current status of the integration (active, inactive, pending)
organization.id	string	Yes	Unique identifier of the associated organization
organization.key	string	Yes	Organization key or slug used within Unizo
createdDateTime	string	Yes	Timestamp when the integration was created

Example Payload

{
  "type": "integration:created",
  "version": "1.0.0",
  "contentType": "application/json",
  "integration": {
    "id": "4f56a3e2-18c2-441a-b95e-c64bde1832a2",
    "name": "Freshworks-GRC",
    "type": "ITSM",
    "status": "active"
  },
  "organization": {
    "id": "167400081",
    "key": "unizo-platform"
  },
  "createdDateTime": "2025-05-05T18:22:10Z"
}

Response

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

Integration Updated

integration:updated

Triggered when configuration or credentials of an existing integration are modified.

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

Headers

Name	Type	Required	Description
x-unizo-event-type	string	Yes	Type of event triggered
x-unizo-signature	string	Yes	HMAC SHA-256 signature for payload verification

Request Body Schema

Property	Type	Required	Description
type	string	Yes	Event type identifier
version	string	Yes	Webhook payload version
contentType	string	Yes	Content type of the webhook payload
integration.id	string	Yes	Unique identifier for the integration
integration.name	string	Yes	Display name of the integration
integration.type	string	Yes	Integration category, e.g., SCM, HRIS, ITSM
integration.status	string	Yes	Current status of the integration
integration.previous_state	object	No	Previous configuration before update
integration.updatedDateTime	string	Yes	Timestamp of the update

Example Payload

{
  "type": "integration:updated",
  "version": "1.0.0",
  "contentType": "application/json",
  "integration": {
    "id": "4f56a3e2-18c2-441a-b95e-c64bde1832a2",
    "name": "Freshworks-GRC",
    "type": "ITSM",
    "status": "active",
    "previous_state": {
      "status": "inactive"
    },
    "updatedDateTime": "2025-05-07T09:42:31Z"
  }
}

Response

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

Integration Deleted

integration:deleted

Triggered when an integration is disconnected or permanently deleted from Unizo.

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

Headers

Name	Type	Required	Description
x-unizo-event-type	string	Yes	Type of event triggered
x-unizo-signature	string	Yes	HMAC SHA-256 signature for payload verification

Request Body Schema

Property	Type	Required	Description
type	string	Yes	Event type identifier
version	string	Yes	Webhook payload version
contentType	string	Yes	Content type of the webhook payload
integration.id	string	Yes	Unique identifier for the integration
integration.name	string	Yes	Display name of the integration
integration.type	string	Yes	Integration category, e.g., SCM, HRIS, ITSM
organization.id	string	Yes	Unique identifier of the associated organization
deletedDateTime	string	Yes	Timestamp when the integration was deleted

Example Payload

{
  "type": "integration:deleted",
  "version": "1.0.0",
  "contentType": "application/json",
  "integration": {
    "id": "4f56a3e2-18c2-441a-b95e-c64bde1832a2",
    "name": "Freshworks-GRC",
    "type": "ITSM"
  },
  "organization": {
    "id": "167400081"
  },
  "deletedDateTime": "2025-05-09T11:10:12Z"
}

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:

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

A webhook delivery is marked as failed if:

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

Best Practices

1. Idempotency

Idempotent Webhook Handler

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

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

await processWebhook(request.body);
await markProcessed(deliveryId);

return { status: 200 };
}

2. Asynchronous Processing

Queue Webhook for Async Processing

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

webhookQueue.add(req.body);
res.status(200).send('OK');
});

3. Error Handling

Webhook Error Handling Example

async function processWebhook(payload) {
try {
  // Business logic
  await updateIntegrationState(payload);
} catch (err) {
  console.error('Webhook processing failed:', err);
  throw err;
}
}

Troubleshooting

Common Issues

Webhook Logs

Access detailed webhook logs in the Unizo Console:

1. Navigate to your integration
2. Click on "Webhooks" tab
3. View delivery history with request/response details

Need Help?

For webhook-related support:

• Check our Webhook Troubleshooting Guide
• Contact support at support@unizo.ai
• Join our Developer Community