Get notified when data has changed with Finch Webhooks. You can create, test, and manage Finch Webhooks in the Developer Dashboard.
Field Name | Type | Description |
---|---|---|
company_id | string<uuid> | Unique Finch id of the company for which data has been updated. |
account_id | string<uuid> | Unique Finch id of the employer account that was used to make this connection. |
connection_id | string<uuid> | Unique Finch id created when an employer successfully authenticates through Finch Connect that represents a unique connection. Use connection_id to represent a connection, as company_id and account_id are deprecated. |
event_type | string | The type of webhook being delivered. |
data | object | More information about the associated event. The structure of this object will vary per event type. |
Field Name | Type | Description |
---|---|---|
event_type | string | Always account.updated . |
data.status | string | The status of the account. This follows our standard connection status schema. Options are pending , processing , connected , reauth , error_permissions , error_no_acount_setup , disconnected . |
data.authentication_method | string | The method of authentication used to connect this account. Options follow the standard Finch authentication types: credential , api_token , oauth , and assisted . |
job.{job_type}.completed
or job.initial_data_sync_*.succeeded
webhook, your application should use the job_url provided in the event to retrieve additional details on the job’s status,
with the latter also signaling that the data sync has completed and succeeded.
job.data_sync_all.completed
:
Emitted for automated data sync jobs. Additional details can be found in the automated jobs endpoint.
job.w4_form_employee_sync.completed
:
Emitted for automated W4 form synchronization jobs. Additional information is available from the automated jobs endpoint.
job.initial_data_sync_*.succeeded
:
Emitted when automated data sync jobs succeed for the first time. Values: initial_data_sync_org
, initial_data_sync_payroll
.
job.benefit_*.completed
:
Emitted for benefit-related jobs. Additional details are accessible via the manual jobs endpoint, which includes both manual and automated benefit jobs.
data
schema:
Field Name | Type | Description |
---|---|---|
event_type | string | Follows the schema job.{job_type}.completed . {job_type} can be any valid Finch job type such as data_sync_all , benefit_create , or benefit_enroll . |
data.job_id | string<uuid> | The id of the job which has completed. |
data.job_url | string | The url to query the result of the job. |
created
, updated
, or deleted
events on any of our endpoints. This type of event has the following schema:
Field Name | Type | Description |
---|---|---|
event_type | string | Follows the schema {endpoint}.{created|updated|deleted} . {endpoint} can be any Finch endpoint such as company , directory , individual , etc. You can see the full up-to-date list of events in by registering an endpoint in our developer dashboard. |
data | object | The data object schema will change depending on the endpoint. |
data
schemas per endpoint are as follows:
updated
.
created
events will be sent.
Finch-Signature
header consists of a list of signatures (where the signature content begins after “v1,” and is space delimited) to account for secret rotations; there may be multiple signatures present for cases where a secret was rotated. During the verification process, the signature must match at least one signature in the list to be considered valid.{webhook_id}.{webhook_timestamp}.{body}
where webhook_id is the Finch-Event-Id, webhook_timestamp is the Finch-Timestamp, and body is the raw body of the request. The signature is sensitive to any changes, so even a small change in the body will cause the signature to be completely different. This means that you should not change the body in any way before verifying. If the signature does not match the value received in the Finch-Signature
header, reject the webhook. Note: when performing the signature comparison, it is safest to use a constant-time comparison to avoid potential timing attacks.event_type
set to test
200
indicating that the event was successfully delivered.
Finch-Event-Id
.update
event for an individual
before a created
event. You should also use the Finch API to occasionally fetch any missing data. For example, you can fetch an individual if you happen to receive an update
event first.connection_id
corresponding to the company for which the data changed. You should retrieve this ID from Finch in order to map webhook updates to the correct company. A simple workflow for this is to call the /introspect
endpoint after exchanging an auth code for an access token via the /auth/token
endpoint. The /introspect
endpoint contains the connection_id
for the connection associated with the token. You can save this ID in your system to map incoming webhook events to companies based on the connection_id
.