12 - Webhook Replies

When you specify a webhook url in the input of a transaction, DATP will use that URL to contact the client any time the status of the transaction changes.

On the client side it requires more coding than simply polling to get the status, but it has several advantages:

1. The reply is guaranteed, even if there is a network failure or the client system goes down - DATP will just keep trying (with an exponential backoff) until it succeeds.

2. Simplified client code, because it does not need to poll - it can start the transaction and then move on - it does not need to poll.

Webhook replies are cryptographically signed.

Note

While it is possible to read a reply without checking the signature we strongly recommend that you do, to ensure that nobody has tampering with the reply, and nobody is sending fake replies to your client application.

See the Webhooks documentation (opens new window) for details on how signatures can be checked.

A Mock webhook server

While you are developing it may be useful to simulate a client that will receive a webhook replies.

In VSCode, copy the entire folder COURSE-FILES/2.12-webhooks/server-for-webhooks into the top level of your workspace (same level as myProject, but not inside myProject).

Open a new terminal inside VSCode (control-shift-backtick) and run the following:

cd /workspace/server-for-webhooks
yarn install
yarn dev

The mock server will start and tell you the URL you can use for webhooks.

Send webhook replies to http://localhost:33340/notify

Go to the MONDAT test page and choose the null test, and set this URL in the input.

{
  "metadata": {
    "reply": "longpoll",
    "webhook": "http://localhost:33340/notify"
  },
  "data": {
    "afield": "xyz"
  }
}

Run your test, and you will see the transaction status sent to the mock server.

Guaranteed delivery

We can simulate a client system that calls our application to start a transaction, but which goes down before the transaction completes:

1. Try running the test with the mock server not running.
2. Look at the webhook status in the Cache/Archive screen and you will see the webhook scheduled for retry.
3. Press refresh and see the Attempts increasing.
4. Start the mock server, and you'll see it receive the reply, and if you refresh MONDAT the webhook status will now be Not scheduled.