Content Comparison

...

PATCH /webhooks/:id/status 
{ "site_id": "{{site_id}}", "token": "{{token}}", "status": "enabled" }

Alerts

...

configuration

Emails and SMS are sent to notify webhook events stated above.

...

 "on_failure": {
    "contact_emails": [ //email alert recipients. In test environments emails are sent to test recipients set in Configuration/Outbound/Media/Test Emails
      "email@company.com"
    ],
    "contact_mobiles": [],
    "sms_notification_name": "",
    "email_notification_name": "webhook_failure" //do not change
  },
  "on_deactivation": {
    "contact_emails": [ //email alert recipients. In test environments emails are sent to test recipients set in Configuration/Outbound/Media/Test Emails
      "email@company.com"
    ],
    "contact_mobiles": [],
    "sms_notification_name": "",
    "email_notification_name": "webhook_deactivation" //do not change
  },
  "on_failure_recovered": {
    "contact_emails": [ //email alert recipients. In test environments emails are sent to test recipients set in Configuration/Outbound/Media/Test Emails
      "email@company.com"
    ],
    "contact_mobiles": [],
    "sms_notification_name": "",
    "email_notification_name": "webhook_failure_recovered" //do not change
  }

Alert trigger example

Image Added

6. Webhook Statuses

• enabled: The default state after creation. Messages are processed normally, triggering the webhook.

• Paused: Messages are stored while the webhook is in a paused state. The behavior of this state depends on the scenario:

  • Manual pause: No messages will be sent until the webhook is manually re-enabled.

  • Automatic pause: This occurs when a message is not acknowledged by the receiver within 15 seconds. In this case, the message will be retried. If the message fails to be acknowledged after the configured number of retries (retries_until_failure), an on_failure notification will be triggered (via email and/or SMS, depending on configuration). If the maximum number of retries is reached without success, the webhook will be disabled. However, if the message is acknowledged before reaching the retry limit, the webhook will automatically resume sending messages (enabled).

• disabled: The webhook stops functioning and storing messages after an on_deactivation error. It must be manually reactivated.

...

8. Integration Requirements

1. Process Messages as Quickly as Possible

Acknowledging webhook messages within 15 seconds is essential, but processing them as fast as possible ensures your system stays in sync with OneStock’s real-time events.

Why It Matters

• Prevent Backlogs: If messages are processed just under the 15-second limit and events occur more frequently, a backlog will form, causing delays.

• Avoid Desync: Since events are processed in order, slow processing can lead to discrepancies. For example, if events occur every 1 second and your system processes messages every 14 seconds, after an hour, only 257 out of 3600 events will be handled, creating a 55-minute delay.

• Improve User Experience: Faster processing ensures that user-facing features and data remain accurate and up-to-date.

Tips for Faster Processing

• Decouple Processing from Acknowledgment: Use a queuing system to instantly acknowledge messages and process them asynchronously.

• Optimize Handling: Keep message processing efficient and lightweight.

• Scale Dynamically: Use auto-scaling to handle traffic spikes.

• Monitor Performance: Set alerts when processing times approach the 15-second limit.

2. 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.

...