Copy page

Getting Started

Webhooks

Webhooks allow your system to receive real-time notifications when an event occurs in your Fynd account. Instead of polling the Orders API to check if a document is ready, Fynd can push a notification to your server as soon as the fulfillment is complete.

Configuration

You can manage your webhook settings from the Settings page.

1. Select an API Client: Webhooks are configured per API Client.
2. Endpoint URL: Provide a public HTTPS URL on your server where you want to receive POST requests (e.g., https://api.yourdomain.com/webhooks/fynd).
3. Enable Webhooks: Click Enable Webhooks to save the URL, turn delivery on, and generate a fresh webhook secret.
4. Webhook Secret: Once webhooks are enabled, you can rotate the secret separately at any time. This secret is used to verify that requests are actually coming from Fynd.

If you disable webhooks later, Fynd keeps the saved endpoint URL and secret so you can re-enable the integration without re-entering them.

Security Note: Like API Keys, webhook secrets are shown only once upon generation. Store them securely in your environment variables or secret manager.

Supported Events

Fynd supports the following events:

order.fulfillment.completed

Sent when an order created via the API has been successfully fulfilled and the document is ready for download.

Payload Example:

Code
{
  "eventId": "707e776b-0ee7-4ff7-b90d-8c84070bf12e",
  "occurredAt": "2026-03-18T08:00:00.000Z",
  "eventType": "order.fulfillment.completed",
  "apiClientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "orderId": "9a3b2c1d-4e5f-6789-abcd-ef0123456789",
  "orderReference": "ORD-2026-00123",
  "downloadPath": "/api/v0/orders/9a3b2c1d-4e5f-6789-abcd-ef0123456789"
}

Use downloadPath as a relative path against the Fynd API base URL to retrieve the fulfilled document.

order.fulfillment.failed

Sent when an order item fails to fulfil.

Payload Example:

Code
{
  "eventId": "707e776b-0ee7-4ff7-b90d-8c84070bf12e",
  "occurredAt": "2026-03-18T08:00:00.000Z",
  "eventType": "order.fulfillment.failed",
  "apiClientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "orderId": "9a3b2c1d-4e5f-6789-abcd-ef0123456789",
  "orderReference": "ORD-2026-00123",
  "errorMessage": "Order item fulfillment failed. Our support is investigating the issue."
}

Request Headers

Each webhook delivery includes the following HTTP headers:

Header	Description
X-Fynd-Signature	HMAC-SHA256 hex digest of the raw request body, signed with your Webhook Secret
X-Fynd-Event	Event type, e.g. order.fulfillment.completed
X-Fynd-Delivery-Id	UUID of the webhook delivery (same as eventId in the payload)
X-Fynd-Timestamp	ISO 8601 timestamp of when the event occurred (same as occurredAt in the payload)

Security & Signature Verification

Fynd signs every webhook payload to ensure authenticity. The signature is sent in the X-Fynd-Signature HTTP header.

Verifying the Signature

The signature is a HMAC-SHA256 hash of the raw request body using your Webhook Secret as the key.

To verify the signature in Node.js:

Code
const { createHmac, timingSafeEqual } = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
  const sigBuf = Buffer.from(signature);
  const expBuf = Buffer.from(expected);
  if (sigBuf.length !== expBuf.length || !timingSafeEqual(sigBuf, expBuf)) {
    return false;
  }
  return true;
}

// In your route handler:
// const signature = request.headers['x-fynd-signature'];
// const isValid = verifyWebhook(request.rawBody, signature, process.env.FYND_WEBHOOK_SECRET);

Important: Always compare buffer lengths before calling timingSafeEqual. If the lengths differ, timingSafeEqual will throw rather than return false.

Reliability & Retries

• HTTP Responses: Your endpoint should return a 2xx status code quickly to acknowledge receipt.
• Timeouts: Fynd considers a request failed if your server does not respond within 10 seconds.
• Retries: If your server is down or returns an error, Fynd will automatically retry the delivery — up to 6 attempts in total.
• Monitoring: You can view recent delivery attempts and failure reasons in the Activity tab of the Settings screen.

Best Practices

• Idempotency: Webhooks may occasionally be delivered more than once. Ensure your implementation handles duplicate eventId values gracefully.
• Secure Endpoint: Always use HTTPS for your webhook URL.
• Immediate Acknowledgment: Perform heavy processing (like downloading the document) asynchronously after returning a 200 OK to Fynd.