Webhook integration guide

Prerequisites

• Dashboard access with webhook management permissions
• HTTPS endpoint to receive webhook notifications
• Authorization credentials (JWT token or basic authentication token)

Security requirements

• For security, all webhook endpoints must use HTTPS.
• Include authentication in the authorization header using either a bearer token or a basic authentication token. JWT is recommended for long-term use.

Configuration steps

Via API:

Webhooks API methods (delete, get, post, put) are available in our API Documentation.

Request headers

Your endpoint will receive the following headers with each webhook:

Authorization: Bearer your-jwt-token
X-Nexus-Signature-256: sha256=signature_hash
X-Nexus-Timestamp: unix_timestamp
X-Nexus-Event-Type: Page_Create
X-Nexus-Delivery-Id: unique-delivery-uuid
Content-Type: text/xml

Signature verification

Each webhook includes a signature for security verification:

// Example verification (Node.js)
const crypto = require('crypto');

function verifySignature(payload, signature, timestamp, secret) {
    const signingString = `${timestamp}.${payload}`;
    const expectedSignature = crypto
        .createHmac('sha256', secret)
        .update(signingString)
        .digest('hex');
    
    return signature === `sha256=${expectedSignature}`;
}

Monitoring and logs

Dashboard monitoring enables you to:

• View webhook status and recent deliveries
• Download delivery logs as CSV reports
• Monitor failure rates and response times

Log data includes:

• Delivery timestamp
• Response status code
• Response time
• Failure reasons
• Retry attempts

Rate limits and performance

• Webhooks are delivered asynchronously to prevent system impact.
• Concurrent delivery limits apply to prevent overwhelming the endpoints.
• During bulk operations (imports/exports), webhook delivery may be paused.

Timeout and retries

• Timeout: 1 second per request
• Retry logic: Automatic retries with exponential backoff for 5xx errors and timeouts
• Failure tracking: Consecutive failures are monitored.

Failure handling

If your endpoint consistently fails to respond:

1. After multiple consecutive failures, the webhook will be automatically disabled.
2. You will receive a notification about the disabled status.
3. Manual re-enablement is required. Access this through the Dashboard.
4. Failure logs are available for download as CSV reports.

Test your integration

1. Start small: Begin with a single event type.
2. Test signature verification: Implement and test signature validation.
3. Handle edge cases: Test with malformed requests and network issues.
4. Monitor logs: Use Dashboard logs to debug delivery issues.

Webhook not firing

• Verify the event type is correctly selected.
• Check that the webhook is enabled.
• Ensure your endpoint is accessible via HTTPS.

Authentication failures

• Verify your authorization header format.
• Check token expiration for JWT tokens.
• Validate signature verification logic.

Timeout issues

• Ensure your endpoint responds within 1 second.
• Consider asynchronous processing for heavy operations.
• Return 200 OK immediately, process in background.