Skip to Content
APIs & ToolsREST APIWebhooks

Webhooks

Finqu uses webhooks to notify your application about events that happen in the Finqu platform. Here’s how they work, how to register them, and how to securely handle them in your application.

Registering Webhooks

To receive webhooks, you must first register them by making a POST request to the Finqu REST API endpoint /webhooks. You can find more details in the Finqu API documentation . When registering, specify the event topics you want to subscribe to and the URL of your webhook endpoint.

Available Webhook Topics

Finqu supports a variety of webhook topics that allow you to react to changes and events in a store. When registering a webhook, you can subscribe to any of the following topics:

  • orders/update
  • orders/activate
  • orders/partially_fulfilled
  • orders/fulfilled
  • orders/shipments_create
  • orders/shipment_remove
  • returns/create, returns/update, returns/remove
  • carts/create, carts/update, carts/remove
  • newsletter/subscribe, newsletter/unsubscribe
  • theme_blocks/create, theme_blocks/update, theme_blocks/remove
  • theme_placements/create, theme_placements/update, theme_placements/remove
  • customers/create, customers/update, customers/remove
  • payment_methods/create, payment_methods/update, payment_methods/remove (all integrations)
  • payment_method/create, payment_method/update, payment_method/remove (related app only)
  • shipping_methods/create, shipping_methods/update, shipping_methods/remove (all integrations)
  • shipping_method/create, shipping_method/update, shipping_method/remove (related app only)

Choose the topics that are relevant for your integration to receive notifications about those specific events.

How Finqu Webhooks Work

Webhooks in Finqu provide a way for your application to receive real-time notifications about important events that occur within a merchant’s store. This allows you to automate workflows, synchronize data, or trigger custom logic in response to changes in the Finqu platform.

  1. Configuration: You configure webhooks in your Finqu integration by registering them via the API. During registration, you specify:

    • The event topics you want to listen for (such as order.created, product.updated, etc.)
    • The URL of your webhook endpoint (where Finqu will send notifications)
    • Any additional configuration required by your integration Once registered, Finqu will begin monitoring the specified events for your app or extension.

  2. Event Triggering: When a relevant event occurs (for example, a new order is placed or a product is updated), Finqu automatically generates a webhook event. Finqu then sends an HTTP POST request to your registered endpoint. This request includes:

    • A JSON payload containing details about the event (such as the event type, affected resource, and relevant data)
    • Special security headers to help you verify the authenticity of the request
    • Contextual information about the merchant and the event Webhook delivery is designed to be reliable: if your endpoint is temporarily unavailable, Finqu will retry delivery several times before giving up. You should always respond with a 2xx HTTP status code to acknowledge successful receipt.

Webhooks are a powerful way to extend Finqu’s functionality and keep your systems in sync with real-time changes. By handling webhook events, you can automate processes such as order fulfillment, inventory updates, customer notifications, and more.

Implementing Webhook Handling

1. Set Up Your Endpoint

Create an endpoint in your application that accepts POST requests from Finqu.

2. Validate the Webhook Request

Webhook validation is essential to ensure that incoming requests are genuinely from Finqu and have not been tampered with. The validation process consists of several steps:

a. Extract the Signature and Timestamp

Finqu includes a Finqu-Signature header in every webhook request. This header contains both a timestamp and a signature, separated by a comma, for example: t=1234567890,h=abcdef123456...

  • Split the header value by comma to separate the timestamp and signature parts.
  • Extract the numeric timestamp and the signature hash from their respective parts.

b. Get the Request ID

The Finqu-Request-Id header contains a unique identifier for the webhook request. This value is used as part of the signature calculation.

c. Recreate the Signed Content

To verify the signature, you must recreate the exact string that Finqu signed. Concatenate the following values in order:

  • The request ID
  • The raw request payload (as a string, exactly as received)
  • The timestamp

d. Calculate the Expected Signature

Using your API secret (shared only between you and Finqu), calculate an HMAC SHA-256 hash of the concatenated string from the previous step. This produces the expected signature.

e. Compare Signatures Safely

Compare the signature you calculated with the signature from the Finqu-Signature header using a time-safe comparison function. This helps prevent timing attacks.

Example: Webhook Validation Pseudocode

function validateFinquWebhook(payload, headers):
    # a. Extract signature and timestamp
    signatureParts = split(headers['Finqu-Signature'], ',')
    timestamp = split(signatureParts[0], '=')[1]
    signature = split(signatureParts[1], '=')[1]

    # b. Get the request ID
    requestId = headers['Finqu-Request-Id']

    # c. Recreate the signed content
    signedContent = requestId + payload + timestamp

    # d. Calculate the expected signature
    expectedSignature = hmac_sha256(signedContent, YOUR_API_SECRET)

    # e. Compare signatures safely
    return time_safe_equals(expectedSignature, signature)

3. Check for Important Headers

Finqu includes these headers in every webhook request:

  • Finqu-Request-Id: Unique identifier for the request
  • Finqu-Signature: Contains timestamp and signature, e.g. t=1234567890,h=abc123...
  • Finqu-Context: JWT token with merchant information

4. Process the Webhook

payload = get_raw_post_data()
headers = get_request_headers()

if validateFinquWebhook(payload, headers):
    data = parse_json(payload)
    topic = data['topic']

    # Process the webhook based on its topic
    if topic == 'order.created':
        # Handle new order
        pass
    # ...other topics...

    send_http_response(200)
else:
    # Invalid signature
    send_http_response(401)

5. Respond Promptly

Always return a 2xx status code quickly to acknowledge receipt. Process any time-consuming tasks asynchronously.

Security Best Practices

  1. Always validate signatures to ensure requests come from Finqu.
  2. Store your API secret securely.
  3. Implement idempotency by tracking request IDs to avoid duplicate processing.
  4. Use HTTPS for your webhook endpoints.

By following these guidelines, you can securely receive and process events from the Finqu platform in your application.

Last updated on
Rate Limits