Working with Webhooks

Overview

In this guide, you will learn how to:

• Register 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.

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

ℹ️ If you need to update the subscribed_events for this webhook, you will need to first delete the webhook and then re-register it following these same instructions.

Request Example

$ curl --location \
     --request POST 'https://gateway.remote-sandbox.com/v1/webhook-callbacks' \
     --header 'Authorization: Bearer eyJraWQiO...' \
     --header 'Content-Type: application/json' \
     --data-raw '{
				"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 delete the webhook callback you just registered.

Deleting a webhook

If the webhook is not needed anymore, you can delete it.

The delete a webhook callback endpoint is also useful if there is a need to modify a webhook callback registered previously. To modify an already registered webhook callback, you'll have to delete and create it again.

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

First, you'll need to have a webhook callback registered. Then, you can use the POST /sandbox/webhook-callbacks/trigger endpoint to simulate triggering one of the event types.

ℹ️ This endpoint is not available in production.

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.