Webhook Documentation Template

Webhook Configuration

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

Event Type	Description	Trigger Conditions
resource:created	A new resource has been created	Resource creation via API or UI
resource:updated	Resource has been modified	Any resource property change
resource:deleted	Resource has been deleted	Resource deletion

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')
  );
}

Event Details

Resource Events

Resource Created

resource:created

Triggered when a new resource is created in any connected platform.

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

Best Practice: Use a dedicated webhook endpoint that can handle multiple event types. You have two architectural options:
• Single endpoint: https://api.yourapp.com/webhooks/unizo - Route all events to one handler
• Category-based endpoints: https://api.yourapp.com/webhooks/unizo/scm - Route by category (scm, ticketing, etc.) for microservices architecture

Headers

Name	Type	Required	Description
Content-Type	string	Yes	Always application/json
x-unizo-event-type	string	Yes	Event type: resource:created
x-unizo-signature	string	Yes	HMAC SHA-256 signature of the request body
x-unizo-timestamp	string	Yes	Unix timestamp when the event was sent
x-unizo-delivery-id	string	Yes	Unique identifier for this webhook delivery (UUID v4)

Request Body Schema

Property	Type	Required	Description
type	string	Yes	Event type identifier: resource:created
version	string	Yes	Webhook payload version (currently 1.0.0)
contentType	string	Yes	Always application/json
resource	object	Yes	Resource information
resource.id	string	Yes	Unique identifier
resource.name	string	Yes	Resource name
resource.createdDateTime	string	Yes	ISO 8601 timestamp
integration	object	Yes	Integration context
integration.type	string	Yes	Integration type
integration.id	string	Yes	Integration UUID
integration.provider	string	Yes	Platform identifier

Example Payload

{
  "type": "resource:created",
  "version": "1.0.0",
  "contentType": "application/json",
  "resource": {
    "id": "res-123456",
    "name": "My Resource",
    "createdDateTime": "2024-01-15T10:30:00Z"
  },
  "integration": {
    "type": "API",
    "id": "int_123456",
    "provider": "example-provider"
  }
}

Response

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

---

resource:deleted

Triggered when a resource is deleted.

Event Payload:

{
  "type": "resource:deleted",
  "version": "1.0.0",
  "contentType": "application/json",
  "resource": {
    "id": "res-123456",
    "deletedDateTime": "2024-01-15T12:00:00Z"
  },
  "integration": {
    "type": "API",
    "id": "int_123456",
    "provider": "example-provider"
  }
}

Attribute Descriptions:

• resource.id: The ID of the deleted resource
• resource.deletedDateTime: When the resource was deleted

Webhook Retry Policy

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

Best Practices

1. Idempotency

Always design your webhook handlers to be idempotent. Use the x-unizo-delivery-id header to track processed events:

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

Return a 200 status immediately and process webhooks asynchronously:

app.post('/webhooks/api', (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');
});

Rate Limits

Webhook deliveries are subject to the following limits:

• Per Integration: 10,000 webhooks per hour
• Per Endpoint: 1,000 webhooks per minute
• Payload Size: Maximum 5MB per webhook

Troubleshooting

Common Issues

1. Webhooks not received
   • Verify endpoint is publicly accessible
   • Check webhook configuration in Unizo Console
   • Review webhook delivery logs
2. Signature validation fails
   • Ensure you're using the correct webhook secret
   • Verify you're validating the raw request body
   • Check for any body parsing middleware issues
3. Duplicate events
   • Implement idempotency using delivery IDs
   • Check if multiple webhook endpoints are configured
   • Verify retry logic isn't creating duplicates

   Multiple Webhook Registrations: If you have created multiple webhook registrations for the same integration, duplicate events will be sent for each registration. Review all webhook configurations in the Unizo Console.

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

---

How to Use This Template

1. Copy this file and rename it for your specific API (e.g., crm-webhooks.mdx)

2. Update the frontmatter with your API-specific information

3. Customize the components:

   • Update the WebhookHeader props with your API name and description
   • Modify the WebhookEventTable events array with your webhook events
   • Create WebhookEvent components for each detailed event
   • Add relevant code examples
   • Update troubleshooting items specific to your API

4. Add or remove sections as needed for your API

5. Test your documentation to ensure all components render correctly

Component Props Reference

WebhookEventTable:

• events: Array of event objects with type, description, and trigger
• title: Optional section title

WebhookEvent:

• eventName: Display name for the event
• eventType: Technical event type (e.g., "resource:created")
• description: Event description
• schema: Array of schema properties
• examplePayload: JSON example payload
• headers: Optional custom headers array
• responseCodes: Optional custom response codes

WebhookSecuritySection:

• headers: Optional custom security headers
• showSignatureVerification: Show verification code
• verificationLanguage: Language for code example

WebhookCodeExample:

• title: Example title
• description: Optional description
• language: Programming language
• code: Code string

WebhookTroubleshooting:

• items: Array of troubleshooting items
• showWebhookLogs: Show webhook logs section
• supportEmail: Support email address
• troubleshootingGuideUrl: Link to guide
• communityUrl: Link to community