...
| Table of Contents | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
1. Configure your site for webhooks
...
If acknowledgment is not received within the configured time frame, the system will retry sending the message. Notifications regarding errors can be sent via SMS, email, or both.
Events
...
on_failure: Triggered after the maximum number of retries (retries_until_failure) is reached without acknowledgment. Retries count do not include the original message (the first one which was not ackowledged).on_failure_recovered: Triggered when a failed message is later acknowledged during a retry. The retry count resets to 0.on_deactivation: Triggered when the maximum retry attempts are exhausted without recovery. The webhook is automatically disabled and must be manually reactivated.
...
Messages are stored for a week; those older than a week are automatically deleted.
8. Integration
...
Requirements
1.
...
To ensure smooth and reliable communication, it's essential to acknowledge webhook messages swiftly—ideally within 15 seconds—by returning a 202 response code. This approach ensures that OneStock knows your system has received the message, allowing the process to continue without delays.
Why Use a Queuing System?
...
Handling Idempotency in Webhook Integration
When integrating with OneStock's webhook system, it is crucial that your webhook client handles idempotency. OneStock expects all webhook clients to process messages in an idempotent manner to ensure consistency and reliability.
What Is Idempotency?
Idempotency refers to the property of certain operations where executing them multiple times yields the same result as executing them once. In the context of webhooks, this means that if the same message is received more than once, processing it multiple times does not cause unintended side effects or data inconsistencies.
Why Is Idempotency Important?
Due to network issues or other transient problems, a message sent by OneStock might not be acknowledged by your system. In such cases, OneStock will retry sending the same message to ensure it has been received and processed.
If your webhook client does not handle idempotency:
Duplicate processing: The same operation might be performed multiple times (e.g., applying the same order change repeatedly), leading to inconsistent data or errors.
Integration breakdowns: Critical systems like your ERP might encounter conflicts or errors due to repeated operations, potentially disrupting business processes.
How to Handle Idempotency
Use the message-id Header
Each webhook message sent by OneStock includes a unique message-id in the HTTP headers. This identifier is essential for ensuring idempotent processing.
Implement Message Queueing and Asynchronous Processing
Acknowledge Immediately: Upon receiving a webhook message, your system should send an acknowledgement to OneStock immediately.
Enqueue the Message: Store the
message-idand the message payload in a reliable queue for asynchronous processing.Process Asynchronously: Use a separate worker or process to consume messages from the queue and handle the idempotency checks.
Ensure Idempotency in Asynchronous Processing
Store processed message IDs: Maintain a persistent record of all processed
message-ids.Check before processing: Before processing a message from the queue, check if its
message-idexists in your records.If it exists: Skip processing.
If it does not exist: Process the message and then store its
message-id.
Ensure Atomic Operations
To prevent race conditions:
Atomic transactions: Combine the message processing and the storage of the
message-idinto a single atomic transaction.Thread safety: If your application processes messages in parallel, ensure that access to the message ID store is thread-safe.
Example Implementation
Webhook Handler Function
| Code Block | ||
|---|---|---|
| ||
function handleWebhookRequest(request):
messageId = request.headers['message-id']
messageBody = request.body
// Acknowledge the message immediately
sendAcknowledgement()
// Enqueue the message for asynchronous processing
enqueueMessage(messageId, messageBody)
|
Asynchronous Message Processor
| Code Block | ||
|---|---|---|
| ||
function processQueuedMessage():
while true:
message = dequeueMessage()
if message is not null:
messageId = message.id
messageBody = message.body
if isMessageIdProcessed(messageId):
// Skip processing as this message has already been handled
continue
try:
beginTransaction()
// Process the message
processWebhookData(messageBody)
// Record the message-id as processed
storeProcessedMessageId(messageId)
commitTransaction()
except Exception as e:
rollbackTransaction()
logError(e)
// Optionally, re-enqueue the message or handle the failure accordingly
else:
// No messages in the queue, wait or sleep before retrying
wait()
|
Acknowledging Messages
Successful processing: Since you acknowledge messages immediately, ensure that your asynchronous processing handles failures internally without relying on OneStock to retry.
Failed processing: Implement retry mechanisms within your message processor for transient errors.
Network failures: Immediate acknowledgement reduces the chance of network issues causing message retries from OneStock.
Advantages of This Approach
Improved performance: Acknowledging immediately reduces response time and prevents timeouts.
Scalability: Asynchronous processing allows your system to handle a higher volume of messages efficiently.
Reliability: Queueing messages ensures they are not lost and can be retried in case of transient failures.
Summary
Handle retries gracefully: Design your webhook client to process duplicate messages without adverse effects.
Use
message-idfor idempotency: Leverage the uniquemessage-idheader provided by OneStock for tracking.Process asynchronously: Acknowledge messages immediately and process them in a separate worker or process.
Prevent duplicate operations: Ensure that repeated messages do not cause inconsistent states or errors in your systems.
8. Integration Best practices
Use a Queuing System to Receive Messages
To ensure smooth and reliable communication, it's essential to acknowledge webhook messages swiftly—ideally within 15 seconds—by returning a 202 response code. This approach ensures that OneStock knows your system has received the message, allowing the process to continue without delays.
Why Use a Queuing System?
Immediate Acknowledgment: By decoupling message reception from processing, you can instantly acknowledge the receipt of the message. The queue receives and stores the message, allowing your system to process it asynchronously without holding up the response.
Enhanced Reliability: A queuing system provides a buffer, ensuring that even if your system is temporarily down or under heavy load, messages are not lost. They will be processed once your system is ready.
Easier Troubleshooting: Queuing services often come with tools that allow you to view and manage received messages, making it easier to diagnose and resolve any communication issues.
...
AWS SQS (Simple Queue Service)
Google Cloud Pub/Sub
Apache Kafka
...
Log Message Reception
If you choose not to use a queuing system, it's vital to implement robust logging of all received messages. Logging should include the message content and the response sent back to OneStock.
Benefits of Logging:
Monitoring and Auditing: Detailed logs provide a trail of received messages, which is crucial for monitoring system performance and ensuring that all messages are accounted for.
Incident Response: In the event of an issue, logs enable you to quickly identify and address the problem, minimizing downtime and maintaining communication integrity.
Compliance and Debugging: Logs can also serve as an essential resource for compliance and debugging purposes, helping you ensure that your system meets all necessary requirements and functions as expected.