



Have any questions? We’re here to help You
All Makini webhooks include a signature header for verification. The signature is an HMAC hash of the webhook payload using your webhook secret as the key. To verify a webhook, compute the HMAC using your secret and compare it to the signature header using constant-time comparison to avoid timing attacks. Never process webhook data without verification, as this could expose your system to forged requests. Your webhook secret is provided when you configure webhooks and should be stored securely. Webhook verification ensures that only legitimate requests from Makini are processed by your application.
Makini implements automatic retry logic for failed webhook deliveries. If your endpoint is unavailable or returns an error status code, we retry delivery with exponentially increasing intervals starting at 30 seconds. Retries continue for up to 24 hours. If delivery ultimately fails, the webhook is logged but not delivered. You can view failed webhooks in the Makini dashboard and manually retry them. To prevent webhook loss during extended downtime, implement a polling backup strategy—periodically check the sync status and query for recent changes if no webhooks have been received within the expected time window. Design your webhook receiver to be idempotent, as retry logic may result in duplicate deliveries.
Design your webhook receiver to handle duplicates and out-of-order webhooks, as network issues or retries can cause both scenarios. Keep the receiver lightweight—ideally writing incoming webhooks to a queue or reliable storage—then process them asynchronously. This prevents timeouts and allows your system to handle high-volume webhook spikes. Respond with a 200 status code immediately after receiving the webhook, before processing begins. Implement idempotency by tracking processed webhook IDs and skipping duplicates. Use constant-time comparison for signature verification to prevent timing attacks. If webhook processing fails, log the error but still return 200 to prevent unnecessary retries. Set up monitoring and alerts for webhook failures so you can investigate issues promptly. For critical workflows, combine webhooks with periodic polling as a fallback mechanism.
Makini uses standard HTTP status codes and structured error responses. Error responses include an error code (e.g., `AUTHENTICATION_FAILED`, `RATE_LIMIT_EXCEEDED`), error type for categorization, a human-readable error message, and a unique request ID for support inquiries. Common status codes include 400 for invalid requests, 401 for authentication failures, 403 for permission issues, 429 for rate limiting, 500 for server errors, and 503 for service unavailability. Use the error code for programmatic error handling rather than parsing error messages. The request ID helps our support team quickly identify and investigate specific issues.
