Events are better than webhooks

There are two methods external SaaS API's use to get data from their system into your system:

Webhooks
- This is a URL that is served by your own webserver.
- The SaaS API makes an HTTP POST request to your server, the payload is an event.
- You must set your webhook URL in the SaaS admin UI (they need to know where to post the data).
Events
- This is an SaaS API endpoint that is polled. It returns all events that have occurred since last time you asked.

They achieve the same thing, but there are small differences that could make a large impact on the consistency and reliability of your business.

	Events	Webhooks
A. Does not require external webserver or SaaS admin config (quickly use with many different env's/accounts)	✔	x
B. Maintains data consistency (event ordering)	✔	x
C. Can recover from downtime instantly, regardless of duration	✔	x
D. Least server resources used	✔	x
E. Easily edit and replay different timelines	✔	x

A. Does not require external webserver or SaaS admin config

Webhooks require that the SaaS API know exactly where to HTTP POST the events.

Polling /events on the other hand does not require a public facing webserver accepting external connections.

A process that polls /events just needs an outbound internet connection which is much easier to initially set up and maintain over time.

B. Maintains data consistency

Ordering of events may be important.

With webhooks, ordering is undefined, and if any webhook handlers fail or are unreachable, the SaaS API will retry the failed webhooks in an undefined order.

By contrast /events is always in a consistent order, which means those events are applied in database transactions which are reproducible.

Webhooks limit database transactions to 1 event per database transaction - the order of these transactions are undefined.

/events allows database transactions to have 100 events per database transaction - the order of these transactions are always the same.

Ordering of events can also be important for SQL triggers and other SQL code designed to maintain data consistency (ACID). If you are developing code that runs inside your SQL engine, you do not want the order of events to change between your dev and production environments.

C. Can recover from downtime instantly, regardless of duration

When webhooks fail, they retry at random intervals for the next few days. If your server misses these retries your database will be in an inconsistent state which will require your manual intervention to fix.

With /events, you can wait 2 weeks and apply all of the un-applied events up until now, and your system will be back to a consistent state.

D. Least server resources used

The /events result set is a list, which naturally multiplex's up to 100 events into a single request/response.

Webhooks are always one request per event. Webhhooks use 100x more HTTP connections/handlers/database transactions than /events.

E. Easily edit and replay different timelines

A list of events, like the ones that are returned from /events, can easily be mocked and replayed for testing purposes. You may save and restore events from real interactions with the API.

You can do the same for webhooks, but the HTTP request/response machinery makes this more complex (especially with the fact that the events can potentially arrive in any order).