Testable Payment Webhooks
PSPs are prioritizing their engineers' experience above anyone else's
There’s something I don’t understand about the way PSPs approach webhooks.
When payments cannot be authorized immediately, the provider and your payment system can communicate in only two ways:
Pull-based communication: The immediate response lets you know that the outcome hasn’t been determined. You now have to build a cron job that will repeatedly request the status of the request to the end provider. You don’t have any clue as to when the status will change.
Push-based communication: You requested a task to be done, and as part of that request, you included a piece of information, called
callback_urlfor example, on which the external provider is going to make a particular request, with a particular payload, that will data regarding the outcome of the task. When that particular request is going to take place is not known in advance.
I remember a tech lead I used to work with was so paranoid about not receiving the events in push-based comms, she bludgeoned us to implement both modes of communication running in parallel.
We traded the unlikely risk that the PSP was unreliable for the very likely risk that we made a concurrency error.
Push-based communication, known as webhooks, is pretty much an industry standard. It is a more efficient way to know when the payment has gone through. The alternative is to repeatedly request the status of the order every few seconds, until it changes.
But that’s not the whole story, no.
Because there are also two ways in which you can configure this callback_url.
On the one hand, you can send this url as part of the request, as I suggested in Never Make a Status Request Again. Each request is associated with a URL that will be notified when an event gets created.
On the other, you can set it up once and forget about this at all. The provider allows you to add this URL on their dashboard. And it becomes the url for all event notifications, for all requests.
The first one is pretty simple for payment engineers to adopt. The second one is easier to implement for the PSP, and creates a terrible experience for you.
Now guess which one is more common.
This is The Payments Engineer Playbook. If you’re new here, this is the only newsletter in the world focused on those building money software, so that they become more effective at their jobs.
Today, we’re looking at webhooks: the segment of the payment flow that’s meant to make customers’ lives easier, but it makes the engineers’ lives a terrible testing nightmare.
This article focuses on:
How are webhooks typically tested
What an amazing developer experience looks like when testing webhooks
What to do when you can’t change your PSP’s design
And the surprising reason why PSPs take one approach, while orchestration platforms take a completely different one.
Let’s get started.