Webhook integration guide

Prerequisites

• Webhooks enabled. Reach out to Support to enable Webhooks if you do not have it on your site yet.
• 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-Delivery-Id: unique-delivery-uuid
X-Nexus-Wiki-Id: your-site-wiki-id
X-Nexus-Page-Id: page-id-that-triggered-the-event
X-Nexus-Event-Type: Page_Create
X-Nexus-Subscription-Id: your-webhook-subscription-guid
X-Nexus-Webhook-Url: the-registered-destination-url
Content-Type: text/xml

X-Nexus-Wiki-Id and X-Nexus-Page-Id identify the site and page that triggered the event. X-Nexus-Subscription-Id and X-Nexus-Webhook-Url echo back your subscription's ID and registered URL, useful if a single endpoint receives deliveries for multiple subscriptions.

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.

Batching

• Events are accumulated per site for up to 5 seconds or 60 events (whichever comes first) before being flushed for delivery.
• This means deliveries may arrive in small batches rather than strictly one at a time, and there can be a delivery delay of up to approximately 5 seconds after the triggering action.

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 subscription is permanently deleted — it is not merely paused or disabled.
2. There is currently no re-enablement path. You must create a new webhook subscription with the same configuration if delivery was interrupted by transient endpoint downtime.
3. 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.