Webhooks - Nmbr

Registering Webhooks

Before receiving webhook calls a webhook URL must be registered using the Webhook API Endpoint.

Webhook Structure

Webhooks across the Nmbr API follow a consistent JSON structure that includes:

the event
the resource
- type
- identifier
- external reference (external_ref), if the resource type supports setting an external reference
- company identifier, if the resource type is scoped to a company

The webhook call made when a business entity is created would have the following properties:

{
  "event": "resource_created",
  "resource": {
    "type": "business_entity",
    "id": "<id>",
    "external_ref": "<ref>",
    "company_id": "<id>"
  }
}

The webhook call made when a company is created would have similar properties:

{
  "event": "resource_created",
  "resource": {
    "type": "company",
    "id": "<id>",
    "external_ref": "<ref>"
  }
}

Note that the call doesn’t include the company_id property because the resource is the company itself and so its identifier is in the id property. The webhook structure does not contain additional entity data. It is recommended the receiving system performs a GET request for the specific entity to retrieve the most up-to-date resource.

Webhook Security

Nmbr will automatically generate a key for each webhook created. Any outgoing webhook calls will include a Webhook-Signature header with an HMAC SHA256 hash of the payload using the webhook key. Consumers may calculate their own signature using the known key and payload to compare to the request header. If the resulting signatures match the developer can be confident the request came from Nmbr.

Webhook Events

Most resources support 3 standard events:

resource_created
resource_updated
resource_deleted

Some resources have additional events that can be used to determine the state of the resource:

payroll_approved

The following table outlines each resource and the corresponding supported events.

Resource	Type	Supported Events
Accounting Code	`accounting_code`	`resource_created` `resource_updated` `resource_deleted`
Accounting Code Rule	`accounting_code_rule`	`resource_created` `resource_updated` `resource_deleted`
Adjustment	`adjustment`	`resource_created` `resource_updated` `resource_deleted`
Allowance	`allowance`	`resource_created` `resource_updated` `resource_deleted`
Async Task	`async_task`	`async_task_completed`
Bank Account	`bank_account`	`resource_created` `resource_updated` `resource_deleted`
Business Entity	`business_entity`	`resource_created` `resource_updated` `resource_deleted` `integration_authentication_success` `integration_authentication_failure` `integration_sync_account_codes_complete` `integration_sync_account_codes_failure` `integration_sync_tags_complete` `integration_sync_tags_failure`
Business Preset	`business_preset`	`resource_created` `resource_updated` `resource_deleted`
Company	`company`	`resource_created` `resource_updated` `resource_deleted`
Contractor	`contractor`	`resource_created` `resource_updated` `resource_deleted`
Deduction	`deduction`	`resource_created` `resource_updated` `resource_deleted`
Earning	`earning`	`resource_created` `resource_updated` `resource_deleted`
Employee	`employee`	`resource_created` `resource_updated` `resource_deleted`
Employee Benefit	`employee_benefit`	`resource_created` `resource_updated` `resource_deleted`
Employer Benefit	`employer_benefit`	`resource_created` `resource_updated` `resource_deleted`
Form Batch	`form_batch`	`form_batch_completed`
Overtime Rate	`overtime_rate`	`resource_created` `resource_updated` `resource_deleted`
Pay Rate	`pay_rate`	`resource_created` `resource_updated` `resource_deleted`
Pay Schedule	`pay_schedule`	`resource_created` `resource_updated` `resource_deleted`
Pay Split	`pay_split`	`resource_created` `resource_updated` `resource_deleted`
Pay Stub	`pay_stub`	`resource_created` `resource_updated` `resource_deleted` `pay_stub_available`
Payroll	`payroll`	`resource_created` `resource_updated` `resource_deleted` `payroll_approved` `payroll_unapproved` `payroll_paid` `payroll_deadline_upcoming` `integration_sync_journal_entries_complete` `integration_sync_journal_entries_failure`
Reimbursement	`reimbursement`	`resource_created` `resource_updated` `resource_deleted`
Remittance Account	`remittance_account`	`resource_created` `resource_updated` `resource_deleted`
Remittance Account Enrollment	`remittance_account_enrollment`	`resource_created` `resource_updated` `resource_deleted`
Tag	`tag`	`resource_created` `resource_updated` `resource_deleted`
Tag Group	`tag_group`	`resource_created` `resource_updated` `resource_deleted`
Vacation Pay Setting	`vacation_pay_setting`	`resource_created` `resource_updated` `resource_deleted`
Work Assignment	`work_assignment`	`resource_created` `resource_updated` `resource_deleted`

​Registering Webhooks

​Webhook Structure

​Webhook Security

​Webhook Events

Registering Webhooks

Webhook Structure

Webhook Security

Webhook Events