Event consumption using webhooks

This page content applies to SaaS only. To receive the event payloads via POST call, the webhook server must perform some actions.

The actions are as follows:
  • Validate the provided Oauth token.
    • If the token is expired or otherwise invalid, respond with the appropriate 40x response code.
    • If the provided token is valid, store the message in a manner where data loss is unlikely to occur. It is suggested to store the message by writing to a Kafka topic, JMS queue, file system, or a database.
  • Respond to the POST call with a 200 message once data is persisted in some manner.
If data validation is required, it is strongly recommended to have the next stage perform any required validation rather than delay a prompt response. The response delays can be mistaken for timeout errors that leads to data re-publishing. This has the potential to have a cascading effect where messages are repeatedly published because the server is not responding promptly and slows the webhook response time even further.

When implementing the webhook server, you need to pay close attention to the webhook's response time. Any request that does not receive a response within 5 seconds is considered to have failed and is retried. If the retried message continues to fail for some reason, the system considers this as failed event delivery and the payload moves to the failed event processing queue.

If your webhook responds with an error code indicating that the token is expired (401), we will attempt to generate and use a new token, unless doing so has already failed to generate a valid token. In that case, we will route the event to the failed event processing queue.

The system recognizes that the Oauth server that is provided is likely not scaled to receive the same volume of requests that the webhook server is. To reduce the number of calls to the Oauth server, the system attempts to refresh the Oauth token approximately 30 minutes prior to expiration.

You can provide the token duration in the following two ways:
  • When the webhooks is on boarded, you can provide the token validity in number of hours. In case the validity changes, update the server with the new duration.
  • You can include the token duration in seconds in the expires_in field in the body of the Oauth response. This allows the system to calculate when the token expires each time it is generated and allows you to make changes to token duration.
    Note: It is recommended that the tokens generated last a minimum of one hour.