Webhooks Documentation

1. Webhook Overview

Webhooks are automated HTTP messages sent from OuViTel™ to your application when specific events occur.

Webhooks enable real-time integration with automation platforms such as Zapier, n8n, Make, or custom backend systems.

Webhooks are exclusively available for Premium license holders.

2. Availability & Licensing

Webhook functionality is a Premium-only feature:

• Best Effort License: Webhooks are not available. Customers must use polling or direct API calls for status updates.
• Premium License: Webhooks are fully supported with guaranteed delivery attempts, retry mechanisms, and integration with the 99.50% uptime SLA.

To enable webhooks, upgrade to a Premium license through your dashboard.

3. Supported Events

OuViTel™ currently supports the following webhook events:

• print.success - Print job completed successfully
• print.failure - Print job failed to complete
• printer.offline - Printer has gone offline (no heartbeat for 60+ minutes)
• printer.online - Printer has come back online
• all - Receive all webhook events (useful for development and testing)

4. Webhook Payload Format

All webhook payloads follow this JSON structure:

{
  "event": "print.success",
  "payload": {
    "jobId": "job_123456",
    "printerToken": "abc123",
    "timestamp": "2026-01-06T12:00:00Z"
  },
  "timestamp": "2026-01-06T12:00:00Z"
}

Common Fields:

• event: The type of event that occurred
• payload: Event-specific data
• timestamp: When the event occurred (ISO 8601 UTC format)

5. Security

Every webhook request includes a security signature that you should verify to ensure the request is genuinely from OuViTel™.

OuViTel™ includes an X-Ouvitel-Signature header with each webhook request. This header contains an HMAC-SHA256 hash of the request body using your webhook's secret key.

Webhook signatures are generated using the raw request body. Ensure your framework does not modify or re-stringify the payload before verification.

All custom headers are prefixed with X-Ouvitel-.

Signature Verification Example:

const crypto = require('crypto');

const signature = req.headers['x-ouvitel-signature'];
const expected = crypto
  .createHmac('sha256', webhookSecret)
  .update(JSON.stringify(req.body))
  .digest('hex');

if (signature !== expected) {
  return res.status(401).send('Invalid signature');
}

6. Webhook Delivery

OuViTel™ provides reliable webhook delivery for Premium customers:

• Failed webhooks are retried up to 5 times with exponential backoff
• Webhook delivery is part of the Premium SLA (99.50% uptime)
• Delivery logs are retained for 30 days for monitoring purposes

Customers are responsible for webhook endpoint availability and proper error handling.

7. Best Practices

To ensure reliable webhook integration, follow these best practices:

• Always verify webhook signatures to prevent unauthorized calls
• Respond with HTTP 200 within 5 seconds of receiving a webhook
• Implement idempotency in your webhook handlers to handle duplicates
• Use HTTPS endpoints only (HTTP endpoints are not accepted)
• Monitor webhook delivery status in your dashboard
• Store your webhook secret securely and never expose it in client-side code

8. Customer Responsibilities

Premium customers using webhooks are responsible for:

• Webhook endpoint availability and security
• Proper signature verification using HMAC-SHA256
• Handling retry attempts gracefully
• HTTPS endpoint configuration and SSL certificate maintenance
• Proper error handling and logging on their webhook endpoints

OuViTel™ is not responsible for third-party webhook endpoint failures or misconfigurations.

9. Integration Examples

Webhooks integrate seamlessly with popular automation platforms:

• Zapier: Use "Webhook by Zapier" trigger with OuViTel™ webhook URL
• n8n: Use "Webhook" node to receive OuViTel™ events
• Make (Integromat): Use "Custom Webhook" module for real-time triggers
• Custom Applications: Implement webhook endpoint following security guidelines

10. Monitoring & Troubleshooting

Webhook delivery status can be monitored through your dashboard:

• View active webhooks and their configuration
• Monitor delivery success/failure rates
• Access webhook secret for endpoint configuration
• Delete or update webhooks as needed

If webhooks are failing, check your endpoint logs and ensure proper signature verification is implemented.

11. Contact

Urimata Ltda.

São Paulo – Brazil

Email: support@ouvitel.com