Webhook consumer best practice

Subscribe only to events that you need

Subscriptions should include only the events required by your endpoint. Subscribing to extra events will place additional load on your server and provide no benefit.

You can view and edit the events in a subscription in Webhooks in the VCC admin portal.

Handle duplicate events

VCC webhook events might sometimes be duplicated. Ensure that your server can handle this by either ignoring the duplicate or ensuring that processing the event again is idempotent.

Reorder events

VCC webhook deliveries are not guaranteed to be in the same order they are generated. Use the event timestamps to determine logical event order.

Use a publicly accessible subscription URL

For the webhook request to reach your server, the URL must be publicly accessible. For example, using localhost will result in delivery failure.

To test your webhook consumer in development, consider using a proxy such as ngrok.

Respond with successful HTTP status codes

Your server must respond with a success status code (any status code between 200 OK and 205 Reset Content) to VCC webhook requests. Anything other than a 2xx code will cause Vonage servers to re-attempt delivery for up to 24 hours.

Acknowledge events quickly

VCC webhook requests have a 10-second timeout. If they do not receive a response from your server within this time, the requests will be considered a failed delivery and be retried.

Ideally your server should respond much faster than this, to avoid scalability issues.

Consider asynchronous processing

Consider using a queue to store received events before more complex processing takes place. This supports fast webhook responses and will allow your server to process events at a rate it can manage, helping to avoid scalability issues.