Skip to main content

Best Practices to Handle Notification

The guidelines to handle the notifications are given below.

  • Use HTTPS Endpoint It is secure and there cannot be MITM attacks because GoBiz verifies that the name on the server certificate matches with the host name. In addition to this, do not use self-signed certificates.
  • Use Notification Callback URL Use standard port (80/443) for Notification Callback URL.
  • Implement Notification in an Idempotent Way In extremely rare cases, GoBiz may send multiple notifications for the same event. It should not cause double entries at your end. To prevent this, Idempotency-Key can be used to track the entries.
  • Use Signature Key Check the Signature Key of the notification. It confirms that the notification is actually sent by GoBiz. We encode the shared secret (server) key. Nobody else can build this signature hash.
  • Reduce the Response Time GoBiz sets the HTTP timeout to fifteen seconds. Please strive to keep the response time of the HTTP notifications under five seconds.
  • Ignore Delayed Status Notifications In extremely rare cases, GoBiz may send the HTTP notifications that are not in the correct sequence. Please handle such cases gracefully.
  • Use JSON Parser We send the notification body as JSON. Therefore, please parse the JSON with a JSON parser. New fields get added to the notification body. Parse the JSON in a non-strict format, so that when the parser sees new fields, it should not throw exception. It should gracefully ignore the new fields. This allows GoBiz to extend its notification system for newer use cases without breaking old clients.
  • Use the Correct HTTP Status Code Always use the correct HTTP status code for responding to the notification. GoBiz handles retry for error cases differently based on the status code.
    • For 2xx: No retries, it is considered success.
    • For 500: Retry only once.
    • For 503: Retry four times.
    • For 400/404: Retry two times.
    • For 301/302/303: No retries.
    • For 307/308: Follow the new URL with POST method and same notification body. Max redirect is five times.
    • For all other failures: Retry five times.
  • Retry at the Most Five Times GoBiz enables retry at the most five times with following policy.
    • Different retry intervals from first time to fifth time (2 minutes, 10 minutes, 30 minutes, 1.5 hours, 3.5 hours).
    • Put a time shift for each retry based on the above interval. For example, for the first time, retry might be two minutes after the job failed. The second retry might be 10 minutes after the first retry is failed, and so on.