Best Practices

We recommend following these best practices to ensure the security and performance of your application.

Subscribe to only the webhook events that your application needs

This can help reduce the amount of events that your server needs to process.

Ensure that your event handlers are idempotent

Duplicate events may occur as a result of concurrent processing within our system, so your application’s webhook endpoint may occasionally receive the same event multiple times.

Achieving idempotency can be accomplished by monitoring the processing status of webhook events in your application. In each event payload, Gusto provides a uuid, a unique identifier for the webhook event. Storing these UUIDs in a table enables your application to determine whether an event has already been processed.

Return a 2xx response promptly

Your server should respond with a 2xx response to confirm successful receipt of a webhook event delivery. Without it, Gusto will continue to retry sending the webhook to your application. This may impact your future webhook deliveries, and Gusto may deactivate your webhook subscription.

Handle events asynchronously

Because delivery order is not guaranteed, we recommend using the event payload's timestamp field, which indicates when the event occurred, to reorder the events in your system.

We also recommend that you set up a queue to help process your event payloads asynchronously. When your application receives a webhook, it should still first respond 2xx to confirm receipt of the event delivery, and then queue the event to be processed asynchronously by your application.

This is beneficial to your application so that you can process events at a rate that your server can handle. It’s possible that Gusto sends a large volume of events in a short amount of time, especially if bulk actions have recently been taken. Implementing asynchronous event processing will ensure that your application can handle such volume spikes and reliably process all incoming webhook requests. It also gives your application more flexibility to manage resources more efficiently.

Prevent subscription deactivations (Demo)

If your subscription frequently fails to respond with a 2xx response, it may be flagged by our system and marked as "unreachable". Subscriptions that are in an "unreachable" state are considered deactivated, and will no longer receive notifications. Our auto-deactivation system flags subscriptions that surpass our failure threshold over a sliding window of time. These failures do not have to be consecutive. Auto-deactivations only affect Demo subscriptions. Production subscriptions are not affected at this time. However, subscriptions across all environments are subject to manual deactivation if we deem their failure rates to be disruptive.

If you plan on testing your subscription in our Demo environment with a server that isn't always available, we recommend deleting it once you have finished testing. Our system will continue attempting to notify all verified subscriptions when a webhook event is triggered through an application. You can delete a subscription in the Developer Portal, or use the "delete a webhook subscription" API.

Reactivate unreachable subscriptions

If your subscription has been deactivated, you can re-activate it in the Developer Portal. Look for your "Unreachable" subscription in the Webhook subscriptions tab, and click "Re-verify" to reactivate it.