Webhook Faqs

👍

Faqs & quick anwser on Webhook management, for details please refer to best practice

Q: How should we respond to webhook events?
A: When you receive webhook events, respond with a success (i.e.200) as quickly as possible.

Q: When and why a reconciliation job is needed?
A: Reconciliation jobs are crucial when your app use cases have to guarantee 100% data integrity and synchronization with SHOPLINE events. This best practice will help your app maintaining complete data accuracy, especially in cases of network issues or service downtime.

Q: How can I understand why a webhook might be missed?
A: Common reasons include network issues, server downtime, errors in webhook handling by the app, payload size limits, strict security or firewall settings, authorization changes, etc. It's important to understand these to manage and mitigate their impact effectively.

Q: How do I handle out-of-sequence webhook events?
A: For applications sensitive to event sequence, incorporate the timestamp from each webhook event into your application logic. This ensures actions are processed in the correct chronological order, based on event trigger times, not receiving times.

Q: What is the concept of webhook idempotence?
A: SHOPLINE's "at least once" delivery feature means an endpoint may receive the same webhook event more than once. Implement deduplication processes in your app to manage duplicate events by comparing 'trace_id' of incoming events with those previously received.

Q: Can you explain more and when to use "application_subscription/update", "subscription_record/start" & "subscription_record/end" ?

A：Please refer to below definition and suggestion

application_subscription/update Webhook This webhook triggers when the merchant updates the auto-renew settings. The merchant can modify this multiple times during subscription period. 該 webhook 在店家修改「下期續訂的訂閱設置」時觸發。店家可以在訂閱期限內多次修改。

subscription_record/start Webhook This event triggers after the system officially creates the subscription record 當系統正式建立訂閱紀錄時觸發

subscription_record/end Webhook This webhook triggers when the subscription ends. 訂閱結束時觸發

Register application_subscription/update if you need to track or react to merchant changes about subscription auto-renewal settings during the active subscription period.

Register subscription_record/start to reliably know when a subscription becomes active for billing, entitlement, or analytics purposes.

Register subscription_record/end to handle subscription ends for access revocation, renewal workflows, or churn analysis etc.

Overall, it is recommended to subscribe to all three webhooks to fully cover the subscription lifecycle, ensuring your system state remains accurate and business logic fits your risk and sync requirements.