Working with Webhooks
Overview
In this guide, you will learn how to:
- Register and delete a webhook
- Test webhooks in the sandbox environment
Before you get started
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](https://www.notion.so/Working-with-Webhooks-f8c1277817ce4d3db10e154e736e6547?pvs=21) and then re-register it following these same instructions.Request Example
ℹ️ 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.
$ 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 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...'
}'
You can find the API documentation for the /v1/webhook-callbacks
endpoint here.
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.
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.
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
payslip.released
webhook event typeSuppose 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 and you'll receive the following response in the registered URL
.
Request Example
$ 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"
}
Webhook Event Response Example
{
"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.
Updated 5 months ago