Working with Webhooks

Overview

In this guide, you will learn how to:

• Register, update and delete a webhook
• Test webhooks in the sandbox environment

Prerequisites

Before you get started, ensure that you’ve created an access token to access the Remote API.

Registering a webhook

If you want to listen to one or more of the changes indicated by our webhook event types, first you need to register a webhook callback. The payload consists of the subscribed_events you want to listen to and the URL our system will call and send the identifier of the resource related to the event. The URL must be unique, so if you want to listen to multiple webhook event types, we suggest registering them all at once.

ℹ️ For each callback, the URL needs to be unique, but an event can be listened to on multiple URLs. For example, you can create two different callbacks with different URLs and include the same event in both and you will be able to listen to that event on both those URLs.

To see the list of available webhook event types, please refer to the API Reference documentation.

Request Example

{
  "subscribed_events": [
    "employment.onboarding_task.completed",
    "payslip.released"
  ],
  "url": "https://example.com/callback"
}

The response to this request will include an id. Make sure you save this ID, as you will need it to update or delete the webhook callback you just registered.

Updating a webhook

To modify a webhook callback, you can use the Update a Webhook Callback endpoint. This can be used to add or remove subscribed events from a specific webhook, or change the URL if needed. To update a webhook, you need to provide the webhook ID returned when you created the webhook in the request body. There's no need to provide the URL again unless you want to update the previously set URL.

{
  "data": {
    "webhook_callback": {
      "id": "0073fcb5-b669-4e4a-b963-2a47744e75a1",
      "subscribed_events": [
        "employment.onboarding_task.completed",
        "timeoff.requested"
      ]
    }
  }
}

In this request, you added a new event and removed an already registered event from the callback.

ℹ️ This call will override the list of events previously registered. So, please make sure to provide all events you want to register for again in this call, otherwise those events will be removed from the list.

Deleting a webhook

If a webhook is not needed anymore, you can delete it using the delete a webhook callback endpoint.

Request Example

$ curl --location \
     --request DELETE 'https://gateway.remote-sandbox.com/v1/webhook-callbacks/3548ce99-bfa1-41f8-9a2b-022c3ff0d3ab' \
     --header 'Authorization: Bearer eyJraWQiO...' 
}'

Testing webhooks in Sandbox

ℹ️ This endpoint is not available in production.

To test a webhook in sandbox, you can use the POST /sandbox/webhook-callbacks/trigger endpoint to simulate triggering one of the event types.

When developing your integration, you’ll usually be working with a locally running server. Your local server will typically accept connections http://localhost:xxxx, but our servers can’t send webhooks directly to your local server since your local server is not exposed to the Internet. We recommend using a reverse proxy or a tunneling service such as ngrok to forward requests to your local server.

🔴 We only recommend using ngrok when testing in the Sandbox environment. Do not use the free version of ngrok in production, as ngrok assigns URLs randomly.
If you forget to delete a registered webhook callback after shutting down the ngrok service, your randomly-assigned ngrok URL may get assigned to another free ngrok user, in which case your webhook data would get sent there.

Example: Testing payslip.released webhook event type

Suppose you want to be notified when an employee's payslip is released. After registering the subscribed_events and the webhook callback URL, send a POST request to the /webhook-callbacks/trigger endpoint with the required parameters.

$ curl --location \
     --request POST 'https://gateway.remote-sandbox.com/v1/sandbox/webhook-callbacks/trigger' \
     --header 'Authorization: Bearer eyJraWQiO...' \
     --header 'Content-Type: application/json' \
     --data-raw '{
		    "employment_id": "5e9e8861-9ead-4a2a-a402-c130bcfac5d6",
		    "event_type": "payslip.released"
			}

You'll receive the following response in the registered URL.

{
    "employment_id": "aab0f8c2-bef6-4b22-b61f-f3fc7357e5ca",
    "event_type": "payslip.released",
    "payslip_id": "a87c2792-sandbox-sample-payslip-693312ee2bee"
}

With the identifier, you can query the Remote API to get the most recent version of the resource. Specifically for the payslip.released event type, if the payslip exists, its identifier will be returned. Otherwise, the Remote API will return the identifier of a sample payslip file. Then, they can be checked using the Download payslip PDF file endpoint.

ℹ️ The sample payslip file is only displayed for testing purposes since it can take some time to have payslips in the test environment, and it does not reflect an actual payslip, as these may have different formats and information depending on each country.

When you’re ready to release your integration, replace the domain with https://gateway.remote.com.
You can find the API documentation for the /v1/webhook-callbacks endpoint here.