Remote Webhooks API
The Webhooks API from Remote — 3 operation(s) for webhooks.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Webhooks API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Webhooks
paths:
/v1/webhook-callbacks/{id}:
delete:
callbacks: {}
deprecated: false
description: 'Delete a callback previously registered for webhooks
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage company resources (`company_admin`) | - | Manage webhooks (`webhook:write`) |
'
operationId: delete_v1_webhook-callbacks_id
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: Webhook Callback ID
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- webhook:write
- company_admin
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- webhook:write
- company_admin
- all:write
summary: Delete a Webhook Callback
tags:
- Webhooks
patch:
callbacks: {}
deprecated: false
description: 'Update a callback previously registered for webhooks
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage company resources (`company_admin`) | - | Manage webhooks (`webhook:write`) |
'
operationId: patch_v1_webhook-callbacks_id
parameters:
- description: Webhook Callback ID
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWebhookCallbackParams'
description: WebhookCallback
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookCallbackResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- webhook:write
- company_admin
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- webhook:write
- company_admin
- all:write
summary: Update a Webhook Callback
tags:
- Webhooks
/v1/webhook-callbacks:
post:
callbacks: {}
deprecated: false
description: 'Register a callback to be used for webhooks
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage company resources (`company_admin`) | - | Manage webhooks (`webhook:write`) |
'
operationId: post_v1_webhook-callbacks
parameters:
- description: 'This endpoint works with any of the access tokens provided. You can use an access
token obtained through the Client Credentials flow, the Authorization Code flow, or the Refresh Token flow.
'
example: Bearer <ANY ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWebhookCallbackParams'
description: WebhookCallback
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookCallbackResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- webhook:write
- company_admin
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- webhook:write
- company_admin
- all:write
OAuth2ClientCredentials:
- https://gateway.remote.com/company.manage
- webhook:write
- company_admin
- all:write
summary: Create a Webhook Callback
tags:
- Webhooks
/v1/companies/{company_id}/webhook-callbacks:
get:
callbacks: {}
deprecated: false
description: 'List callbacks for a given company
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage company resources (`company_admin`) | View webhooks (`webhook:read`) | Manage webhooks (`webhook:write`) |
'
operationId: get_v1_companies_company_id_webhook-callbacks
parameters:
- description: Company ID
example: d2091b1e-b1a4-437a-91ea-2809ffbb6d59
in: path
name: company_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListWebhookCallbacksResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- webhook:read
- webhook:write
- company_admin
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- webhook:read
- webhook:write
- company_admin
- all:write
- all:read
summary: List Webhook Callbacks
tags:
- Webhooks
components:
schemas:
ParameterError:
example:
code: invalid_param
message: Invalid parameter
param: employment_id
properties:
code:
description: An error code that describes the nature of the error.
type: string
message:
description: A developer friendly error message that gives details on what the error was and how it may be remedied.
type: string
param:
description: The parameter that lead to the error message.
type: string
required:
- code
- message
- param
title: ParameterError
type: object
WebhookCallback:
description: A registered webhook callback endpoint. Remote sends HTTP POST requests to the configured URL when subscribed events occur.
example:
id: 0073fcb5-b669-4e4a-b963-2a47744e75a1
subscribed_events:
- employment.onboarding_task.completed
url: https://example.com/callback
properties:
id:
description: The unique identifier (UUID) of the webhook callback.
type: string
signing_key:
description: 'This key will be used to sign the signature provided with webhook requests we
send to the `url` you provided for this webhook callback.
The webhook signature will be included in a custom header, `X-Remote-Signature`.
You can use this signature to verify that requests are coming from Remote and
not some unauthorized third-party.
'
type: string
subscribe_to_all_events:
description: When true, this callback is subscribed to all current and future event types. `subscribed_events` then lists every currently supported event.
type: boolean
subscribed_events:
items:
description: The setting to be enabled.
enum:
- background_check.status.updated
- benefit_renewal_request.created
- billing_document.issued
- company.activated
- company.manager_created
- company.manager_deleted
- company.manager_updated
- company.owner_changed
- company.archived
- company.eor_hiring.additional_information_required
- company.eor_hiring.reserve_payment_requested
- company.eor_hiring.no_reserve_payment_requested
- company.eor_hiring.referred
- company.eor_hiring.verification_completed
- company.partner_offboarded
- company.pricing_plan.updated
- contract_amendment.canceled
- contract_amendment.deleted
- contract_amendment.done
- contract_amendment.review_started
- contract_amendment.submitted
- contract.termination_date_reached
- contract_document.status.changed
- contractor_invoice.employer_paid
- contractor_invoice.issued
- contractor_invoice.paid_out
- contractor_invoice.payment_initiated
- custom_field.value_updated
- employment.benefits.selected
- employment_company_structure_node.updated
- employment_contract.active_contract_updated
- employment_contract.adjusted_during_onboarding
- employment.account.updated
- employment.administrative_details.updated
- employment_basic_information.updated
- employment.contractor_management_plan.updated
- employment.contractor_of_record_termination.cancelled
- employment.contractor_of_record_termination.executed
- employment.contractor_of_record_termination.initiated
- employment.details.updated
- employment.employment_agreement.available
- employment.cor_hiring.invoice_created
- employment.eor_hiring.invoice_created
- employment.cor_hiring.proof_of_payment_accepted
- employment.cor_hiring.proof_of_payment_submitted
- employment.eor_hiring.proof_of_payment_accepted
- employment.eor_hiring.proof_of_payment_submitted
- employment.no_longer_eligible_for_onboarding_cancellation
- employment.onboarding_task.completed
- employment.onboarding.cancelled
- employment.onboarding.completed
- employment.onboarding.started
- employment.personal_information.updated
- employment.probation_completion_letter.cancelled
- employment.probation_completion_letter.completed
- employment.probation_completion_letter.submitted
- employment.probation.period_ending_reminder_sent
- employment.probation_period_extension.cancelled
- employment.probation_period_extension.completed
- employment.probation_period_extension.submitted
- employment.start_date.changed
- employment.status.updated
- employment.updated
- employment.user_status.activated
- employment.user_status.deactivated
- employment.user_status.initiated
- employment.user_status.invited
- employment.work_email.updated
- expense.approved
- expense.declined
- expense.deleted
- expense.reimbursed
- expense.submitted
- expense.updated
- identity_verification.verification_required
- incentive.created
- incentive.deleted
- incentive.paid
- incentive.processing_started
- incentive.updated
- offboarding.completed
- offboarding.deleted
- offboarding.done
- offboarding.review_started
- offboarding.submitted_to_payroll
- offboarding.submitted
- payslip.released
- sso_configuration.disabled
- sso_configuration.enabled
- sso_configuration.updated
- timeoff.approved
- timeoff.canceled
- timeoff.cancellation_requested
- timeoff.date_changed
- timeoff.declined
- timeoff.requested
- timeoff.started
- timeoff.taken
- timeoff.updated
- timesheet.submitted
- timesheet.in_calibration
- travel_letter.approved_by_manager
- travel_letter.approved_by_remote
- travel_letter.declined_by_manager
- travel_letter.declined_by_remote
- travel_letter.requested
- work_authorization.approved_by_manager
- work_authorization.approved_by_remote
- work_authorization.cancelled
- work_authorization.declined_by_manager
- work_authorization.declined_by_remote
- work_authorization.requested
type: string
type: array
url:
description: The HTTPS URL where Remote will send webhook event payloads.
type: string
required:
- id
- url
title: WebhookCallback
type: object
UnauthorizedResponse:
description: Returned when the request does not include valid authentication credentials. Ensure you are passing a valid OAuth2 access token or API token in the Authorization header.
example:
message: Unauthorized
properties:
message:
pattern: Unauthorized
type: string
required:
- message
title: UnauthorizedResponse
type: object
UpdateWebhookCallbackParams:
additionalProperties: false
description: 'Webhook callback update params. Provide either `subscribed_events` or `subscribe_to_all_events` (they are mutually exclusive). Omitting `subscribe_to_all_events` leaves the current subscription mode unchanged, so resending an event list does not disable all-events delivery. Setting `subscribe_to_all_events: false` requires a non-empty `subscribed_events`.'
example:
subscribed_events:
- employment.onboarding_task.completed
url: https://example.com/callback
properties:
subscribe_to_all_events:
description: When true, subscribe this callback to all current and future event types. Cannot be combined with `subscribed_events`.
type: boolean
subscribed_events:
items:
description: The setting to be enabled.
enum:
- background_check.status.updated
- benefit_renewal_request.created
- billing_document.issued
- company.activated
- company.manager_created
- company.manager_deleted
- company.manager_updated
- company.owner_changed
- company.archived
- company.eor_hiring.additional_information_required
- company.eor_hiring.reserve_payment_requested
- company.eor_hiring.no_reserve_payment_requested
- company.eor_hiring.referred
- company.eor_hiring.verification_completed
- company.partner_offboarded
- company.pricing_plan.updated
- contract_amendment.canceled
- contract_amendment.deleted
- contract_amendment.done
- contract_amendment.review_started
- contract_amendment.submitted
- contract.termination_date_reached
- contract_document.status.changed
- contractor_invoice.employer_paid
- contractor_invoice.issued
- contractor_invoice.paid_out
- contractor_invoice.payment_initiated
- custom_field.value_updated
- employment.benefits.selected
- employment_company_structure_node.updated
- employment_contract.active_contract_updated
- employment_contract.adjusted_during_onboarding
- employment.account.updated
- employment.administrative_details.updated
- employment_basic_information.updated
- employment.contractor_management_plan.updated
- employment.contractor_of_record_termination.cancelled
- employment.contractor_of_record_termination.executed
- employment.contractor_of_record_termination.initiated
- employment.details.updated
- employment.employment_agreement.available
- employment.cor_hiring.invoice_created
- employment.eor_hiring.invoice_created
- employment.cor_hiring.proof_of_payment_accepted
- employment.cor_hiring.proof_of_payment_submitted
- employment.eor_hiring.proof_of_payment_accepted
- employment.eor_hiring.proof_of_payment_submitted
- employment.no_longer_eligible_for_onboarding_cancellation
- employment.onboarding_task.completed
- employment.onboarding.cancelled
- employment.onboarding.completed
- employment.onboarding.started
- employment.personal_information.updated
- employment.probation_completion_letter.cancelled
- employment.probation_completion_letter.completed
- employment.probation_completion_letter.submitted
- employment.probation.period_ending_reminder_sent
- employment.probation_period_extension.cancelled
- employment.probation_period_extension.completed
- employment.probation_period_extension.submitted
- employment.start_date.changed
- employment.status.updated
- employment.updated
- employment.user_status.activated
- employment.user_status.deactivated
- employment.user_status.initiated
- employment.user_status.invited
- employment.work_email.updated
- expense.approved
- expense.declined
- expense.deleted
- expense.reimbursed
- expense.submitted
- expense.updated
- identity_verification.verification_required
- incentive.created
- incentive.deleted
- incentive.paid
- incentive.processing_started
- incentive.updated
- offboarding.completed
- offboarding.deleted
- offboarding.done
- offboarding.review_started
- offboarding.submitted_to_payroll
- offboarding.submitted
- payslip.released
- sso_configuration.disabled
- sso_configuration.enabled
- sso_configuration.updated
- timeoff.approved
- timeoff.canceled
- timeoff.cancellation_requested
- timeoff.date_changed
- timeoff.declined
- timeoff.requested
- timeoff.started
- timeoff.taken
- timeoff.updated
- timesheet.submitted
- timesheet.in_calibration
- travel_letter.approved_by_manager
- travel_letter.approved_by_remote
- travel_letter.declined_by_manager
- travel_letter.declined_by_remote
- travel_letter.requested
- work_authorization.approved_by_manager
- work_authorization.approved_by_remote
- work_authorization.cancelled
- work_authorization.declined_by_manager
- work_authorization.declined_by_remote
- work_authorization.requested
type: string
type: array
url:
type: string
title: UpdateWebhookCallbackParams
type: object
WebhookCallbackResponse:
description: Webhook callback response
example:
data:
webhook_callback:
id: 0073fcb5-b669-4e4a-b963-2a47744e75a1
subscribed_events:
- employment.onboarding_task.completed
url: https://example.com/callback
properties:
data:
properties:
webhook_callback:
$ref: '#/components/schemas/WebhookCallback'
required:
- webhook_callback
type: object
required:
- data
title: WebhookCallbackResponse
type: object
CreateWebhookCallbackParams:
additionalProperties: false
description: 'Webhook callback creation params. Provide either `subscribed_events` or `subscribe_to_all_events: true` (they are mutually exclusive).'
example:
subscribe_to_all_events: true
url: https://example.com/callback
properties:
subscribe_to_all_events:
default: false
description: When true, subscribe this callback to all current and future event types. Cannot be combined with `subscribed_events`.
type: boolean
subscribed_events:
items:
description: The setting to be enabled.
enum:
- background_check.status.updated
- benefit_renewal_request.created
- billing_document.issued
- company.activated
- company.manager_created
- company.manager_deleted
- company.manager_updated
- company.owner_changed
- company.archived
- company.eor_hiring.additional_information_required
- company.eor_hiring.reserve_payment_requested
- company.eor_hiring.no_reserve_payment_requested
- company.eor_hiring.referred
- company.eor_hiring.verification_completed
- company.partner_offboarded
- company.pricing_plan.updated
- contract_amendment.canceled
- contract_amendment.deleted
- contract_amendment.done
- contract_amendment.review_started
- contract_amendment.submitted
- contract.termination_date_reached
- contract_document.status.changed
- contractor_invoice.employer_paid
- contractor_invoice.issued
- contractor_invoice.paid_out
- contractor_invoice.payment_initiated
- custom_field.value_updated
- employment.benefits.selected
- employment_company_structure_node.updated
- employment_contract.active_contract_updated
- employment_contract.adjusted_during_onboarding
- employment.account.updated
- employment.administrative_details.updated
- employment_basic_information.updated
- employment.contractor_management_plan.updated
- employment.contractor_of_record_termination.cancelled
- employment.contractor_of_record_termination.executed
- employment.contractor_of_record_termination.initiated
- employment.details.updated
- employment.employment_agreement.available
- employment.cor_hiring.invoice_created
- employment.eor_hiring.invoice_created
- employment.cor_hiring.proof_of_payment_accepted
- employment.cor_hiring.proof_of_payment_submitted
- employment.eor_hiring.proof_of_payment_accepted
- employment.eor_hiring.proof_of_payment_submitted
- employment.no_longer_eligible_for_onboarding_cancellation
- employment.onboarding_task.completed
- employment.onboarding.cancelled
- employment.onboarding.completed
- employment.onboarding.started
- employment.personal_information.updated
- employment.probation_completion_letter.cancelled
- employment.probation_completion_letter.completed
- employment.probation_completion_letter.submitted
- employment.probation.period_ending_reminder_sent
- employment.probation_period_extension.cancelled
- employment.probation_period_extension.completed
- employment.probation_period_extension.submitted
- employment.start_date.changed
- employment.status.updated
- employment.updated
- employment.user_status.activated
- employment.user_status.deactivated
- employment.user_status.initiated
- employment.user_status.invited
- employment.work_email.updated
- expense.approved
- expense.declined
- expense.deleted
- expense.reimbursed
- expense.submitted
- expense.updated
- identity_verification.verification_required
- incentive.created
- incentive.deleted
- incentive.paid
- incentive.processing_started
- incentive.updated
- offboarding.completed
- offboarding.deleted
- offboarding.done
- offboarding.review_started
- offboarding.submitted_to_payroll
- offboarding.submitted
- payslip.released
- sso_configuration.disabled
- sso_configuration.enabled
- sso_configuration.updated
- timeoff.approved
- timeoff.canceled
- timeoff.cancellation_requested
- timeoff.date_changed
- timeoff.declined
- timeoff.requested
- timeoff.started
- timeoff.taken
- timeoff.updated
- timesheet.submitted
- timesheet.in_calibration
- travel_letter.approved_by_manager
- travel_letter.approved_by_remote
- travel_letter.declined_by_manager
- travel_letter.declined_by_remote
- travel_letter.requested
- work_authorization.approved_by_manager
- work_authorization.approved_by_remote
- work_authorization.cancelled
- work_authorization.declined_by_manager
- work_authorization.declined_by_remote
- work_authorization.requested
type: string
type: array
url:
type: string
required:
- url
title: CreateWebhookCallbackParams
type: object
ListWebhookCallbacksResponse:
example:
data:
- id: 0073fcb5-b669-4e4a-b963-2a47744e75a1
subscribed_events:
- employment.onboarding_task.completed
url: https://example.com/callback
properties:
data:
items:
$ref: '#/components/schemas/WebhookCallback'
type: array
required:
- data
title: ListWebhookCallbacksResponse
type: object
NotFoundResponse:
description: Returned when the requested resource does not exist or is not accessible with the current authentication credentials.
example:
message: '{resource} not found'
properties:
message:
description: A message indicating which resource was not found.
pattern: Not Found
type: string
title: NotFoundResponse
type: object
UnprocessableEntityResponse:
anyOf:
- properties:
errors:
type: object
required:
- errors
type: object
- properties:
message:
oneOf:
- type: string
- $ref: '#/components/schemas/ParameterError'
- items:
$ref: '#/components/schemas/ParameterError'
title: ParameterErrors
type: array
- $ref: '#/components/schemas/ActionError'
- items:
$ref: '#/components/schemas/ActionError'
title: ActionErrors
type: array
required:
- message
type: object
example:
errors:
some_field:
- is invalid
title: UnprocessableEntityResponse
type: object
SuccessResponse:
description: A generic success response returned by operations that don't produce a specific resource (e.g., updates, deletes).
example:
data:
status: ok
properties:
data:
properties:
status:
description: The result status. Always `"ok"` for successful operations.
type: string
type: object
required:
- data
title: SuccessResponse
type: object
ActionError:
properties:
action:
description: The action that lead to the error message.
type: string
code:
description: An error code that describes the nature of the error.
type: string
message:
description: A developer friendly error message that gives details on what the error was and how it may be remedied.
type: string
required:
- code
- message
- action
title: ActionError
type: object
securitySchemes:
BasicAuth:
description: 'Authenticate using the basic authentication for partners.
Use the CLIENT_ID as login and CLIENT_SECRET as password.
'
scheme: basic
type: http
ClientToken:
description: 'Authenticate a partner using only the the provided `client_token`.
This authentication method only allows accessing marketing endpoints.
'
scheme: bearer
type: http
CustomerAPIToken:
description: 'Authenticate using API Key generated by the customer in their Integration Settings page.
'
scheme: bearer
type: http
OAuth2:
description: 'Authenticate using OAuth 2.0 protocol.
'
flows:
authorizationCode:
authorizationUrl: /auth/oauth2/authorize
scopes:
company_department:read: company_department:read
webhook:write: webhook:write
magic_link:write: magic_link:write
offboarding:write: offboarding:write
custom_field:write: custom_field:write
address:write: address:write
expense:read: expense:read
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/remote/refs/heads/main/openapi/remote-webhooks-api-openapi.yml