Subscribing to Webhooks

This guide covers how to register, update, list, and delete webhook subscriptions. For how webhooks work and how the pieces fit together, see Introduction to Webhooks. To handle the deliveries once they start arriving, see Receiving Webhooks.

Before you start

You will need:

• A company-scoped access token. Webhooks are always tied to a single company, so managing them requires a company-scoped token. See the guides on obtaining an access token for customers or partners.
• The events you want to listen to. See Available Webhooks for the full catalog.

Register a callback

Register a subscription with the Create a Webhook Callback endpoint. Provide the url Remote should call, then choose the events in one of two ways:

• subscribed_events: an array of specific event names.
• subscribe_to_all_events: set to true to receive every event type.

These two options are mutually exclusive. Send one or the other, not both.

Subscribe to a specific set of events:

curl -X POST https://gateway.remote.com/v1/webhook-callbacks \
  -H "Authorization: Bearer $REMOTE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/callback",
    "subscribed_events": [
      "employment.onboarding_task.completed",
      "payslip.released"
    ]
  }'

Or subscribe to everything:

curl -X POST https://gateway.remote.com/v1/webhook-callbacks \
  -H "Authorization: Bearer $REMOTE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/callback",
    "subscribe_to_all_events": true
  }'

Each callback URL must be unique. To send the same event to more than one destination, register a separate callback for each URL. An event can appear in as many callbacks as you like, so you can fan a single event out to several endpoints.

The response returns the callback id and a signing_key:

{
  "data": {
    "webhook_callback": {
      "id": "fbac1e8a-3f38-4e1a-acbe-f046761171bf",
      "signing_key": "wkyzvs764ifdrpct2naqhksmq4",
      "subscribed_events": [
        "employment.onboarding_task.completed",
        "payslip.released"
      ],
      "subscribe_to_all_events": false,
      "url": "https://example.com/callback"
    }
  }
}

Save the id, because you need it to update or delete the callback later. The signing_key is the secret you use to confirm each delivery came from Remote. Store it securely and see Verifying Webhooks for how to use it. Remote returns the signing key only when you create the callback.

Update a subscription

Use the Update a Webhook Callback endpoint to change the URL or the subscribed events. Provide the callback id in the path.

curl -X PATCH https://gateway.remote.com/v1/webhook-callbacks/{id} \
  -H "Authorization: Bearer $REMOTE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subscribed_events": [
      "employment.onboarding_task.completed",
      "timeoff.requested"
    ]
  }'

List your callbacks

Retrieve the callbacks registered for a company by calling GET /v1/companies/{company_id}/webhook-callbacks:

curl https://gateway.remote.com/v1/companies/{company_id}/webhook-callbacks \
  -H "Authorization: Bearer $REMOTE_API_TOKEN"

Delete a subscription

Delete a callback with the Delete a Webhook Callback endpoint. It takes the callback id.

curl -X DELETE https://gateway.remote.com/v1/webhook-callbacks/{id} \
  -H "Authorization: Bearer $REMOTE_API_TOKEN"

Subscribe from the CLI

If you use the Remote CLI, you can manage callbacks without writing HTTP calls. The webhooks commands operate on your active company.

# Register a callback (prompts for the URL and events if the flags are omitted)
remotecli webhooks create \
  --url https://example.com/callback \
  --events employment.onboarding_task.completed,payslip.released

# List, update, and delete
remotecli webhooks list
remotecli webhooks update <callback-id> --events timeoff.requested,payslip.released
remotecli webhooks delete <callback-id>

remotecli webhooks create prints the signing_key once. Capture it from the output, because the API does not return it again.

Next steps

• Receiving Webhooks: verify deliveries, respond, and recover missed events.
• Verifying Webhooks: confirm each delivery is genuine with the signing key.
• Available Webhooks: the full list of event types you can subscribe to.