Add a Webhook

This tutorial explains how to add a webhook callback to get notified of incoming (received) document transactions.

If you prefer importing this tutorial into Postman or Insomnia, download the har archive file and import into your preferred tool.

Prerequisites

Your user must have the orgadmin role in an existing organisation to be able to proceed with this tutorial. Visit the Create an Organisation tutorial if you do not already belong to an organisation.

You must also be able to send a transaction to yourself in order to trigger the event in this tutorial. If you do not know how to do that, visit the Send a tutorial.

Step 1. List Existing Webhooks

If you are a new customer and it is the first time you run this tutorial your organisation will most likely not have any existing webhooks. But just to make sure, and at the same time test the first webhooks endpoint let us call /orgs/:orgId/webhooks to see what we get.

curl -X GET https://api.arratech.com/orgs/YOUR_ORGS_ID/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

All is good if this calls returns a list of webhook objects, most likely an empty list in our case.

Step 2. Create a Callback Handler

Our future notification for an incoming transaction must be handled somewhere. Typically this is handled by a customer created service but to not make you build such a service as part of this tutorial we will use the free online tool webhook.site for it.

In a new browser window, navigate to https://webhook.site/. This will automatically generate a unique webhook endpoint url for you on the form
https://webhook.site/421d513b-ab88-4006-9c99-000000000000.

On this page you can now in real-time monitor all incoming calls to the generated endpoint url above. Take note of this url because we will use it in the next step.

Step 3. Register the Webhook

We are now ready to register the webhook. For this we need the callback url from the previous step and we also need to know the name of the "received a transaction" event which we are interested in. This we find in the API Documentation and it's transaction.received. We will also add a test event webhook.test which we will use to manually test our webhook once created.

We can now register a new webhook via the /orgs/:orgId/webhooks endpoint.

curl -X POST https://api.arratech.com/orgs/YOUR_ORGS_ID/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "My first hook",
	"events": ["transaction.received", "webhooks.test"],
	"url": "YOUR_WEBHOOK_SITE_URL",
	"isEnabled": true
}'

Take note of the id property value in the returned webhook object since you will need this in the next step. You may also repeat step 1 to verify that the new webhook is visible in the list of all your webhooks.

Step 4. Trigger the Webhook

To trigger the webhook you need to receive a transaction. You can do this for real by running the Send Transaction tutorial again. Feel free to do so and verify that a transaction.received event is listed in your webhook.site page.

The API also contains an endpoint for triggering test events manually. We will use this endpoint, /orgs/:orgId/webhooks/trigger-test-event, to verify our registered webhook with the test event we added earlier. Make sure to use the webhook id you received in the previous step.

curl -X POST https://api.arratech.com/orgs/YOUR_ORGS_ID/webhooks/trigger-test-event \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookIds": [
    "YOUR_WEBHOOK_ID"
  ],
  "testEventType": "webhooks.test",
  "payload": {
    "transactionId": "any-dummy-value",
    "status": "RECEIVED"
  }
}'

After making the call above go to your webhook.site page and verify that the event is received.

Step 5. List Earlier Webhook Events

In the case you need to retrieve the event we triggered above in retrospect you use the /orgs/:orgId/webhooks/events endpoint.

curl -X GET https://api.arratech.com/orgs/YOUR_ORGS_ID/webhooks/events \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Verify that the returned response contains the previously triggered event.

Congratulations! You have registered a webhook to be notified when you receive transactions.