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.
-
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.
- The event topics you want to listen for (such as
-
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 requestFinqu-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
- Always validate signatures to ensure requests come from Finqu.
- Store your API secret securely.
- Implement idempotency by tracking request IDs to avoid duplicate processing.
- Use HTTPS for your webhook endpoints.
By following these guidelines, you can securely receive and process events from the Finqu platform in your application.