Webhooks - Symmetry Docs

Webhooks allow you to receive real-time notifications when important events occur in the I-9 process. You can use them to trigger downstream workflows, update your internal systems, or monitor form progress without polling our APIs.

Events

When an event occurs, a POST request is sent to the configured webhook endpoint. All event types are included—you cannot subscribe to individual events.

Event	`eventKey`	Description
Form I-9 was countersigned	`employee.i9Complete`	Notifies you when an employee’s I-9 is complete and Section 2 is countersigned.
E-Verify case details updated	`employee.everifyCaseUpdate`	Triggered when an employee’s E-Verify case is updated. Use this to prompt internal review or next steps.
Employee profile updated	`employee.profileUpdated`	Notifies you when an employee’s profile is updated (for example, social security number is added). It is not triggered when the employee is created.
I-9 expiring documents	`employee.upcomingExpiration`	Triggers for Employment Authorization Documents (EADs) and Passport receipts 30 days before expiration, or immediately upon I-9 submission if within 30 days. Excludes original Passports. Applies only to active employees.
Employee restarted Form I-9	`employee.i9Restarted`	Notifies you when an employee restarts the Form I-9 process. This event does not include a submission ID because a new submission has not yet been created.
Employee submitted form	`employee.section1Complete`	Fires when an employee completes Section 1, allowing you to prompt administrative review.
Employee submission rejected	`employee.submissionRejected`	Notifies you when an employer rejects an employee’s Form I-9 submission during the review process. Includes the rejection reason.
Employee submission reverified	`employee.submissionReverified`	Notifies you when a Form I-9 has been successfully reverified through Supplement B.
Authorized representative mismatch	`employee.i9AuthRepMismatch`	Triggered when an authorized representative identifies a mismatch while reviewing an employee’s Form I-9 documents during remote countersigning.
E-Verify authentication result	`employer.everifyAuthenticationResult`	Notifies you of the result of an employer’s E-Verify credential authentication attempt (success or failure). This is an employer-level event and does not include employee data.

Webhooks are distinct from the postback serviceWhile webhooks send lightweight notifications about key events (such as form submission or case updates), the postback sends the full completed form data, including the actual form and its values.The postback is sent to the postback.target.url specified in the employers object and is typically used for processing the full I-9 record after completion. Read more here: Receive Completed I-9 Data.

Sample payloads

Form I-9 was countersigned (`employee.i9Complete`)

Sent when Section 2 is countersigned.

{
  "eventKey": "employee.i9Complete",
  "timestamp": "2025-12-22T15:51:19.757Z",
  "data": {
    "employerId": "12345-3fe3-7146-8ea6-123456sdfg",
    "employeeId": "0987654-d7ee-702f-92f3-123456lkjhgf",
    "submission": {
      "id": 1334
    }
  }
}

E-Verify case details updated (`employee.everifyCaseUpdate`)

Sent when an employee’s E-Verify case status changes.

{
  "eventKey": "employee.everifyCaseUpdate",
  "timestamp": "2025-12-22T15:51:26.109Z",
  "data": {
    "employerId": "12345-3fe3-7146-8ea6-123456sdfg",
    "employeeId": "0987654-d7ee-702f-92f3-123456lkjhgf",
    "submission": {
      "id": 1334
    },
    "everifyCase": {
      "caseId": "123456789ghj",
      "closed": false,
      "status": "draft"
    }
  }
}

Employee profile updated (`employee.profileUpdated`)

Sent when the employee’s profile is updated.

{
  "eventKey": "employee.profileUpdated",
  "timestamp": "2024-12-08T22:32:39.398-07:00",
  "data": {
    "employerId": "0197b38a-a7ca-77a1-86fb-f090890338d3",
    "employeeId": "0197b38a-a7ca-77a1-86fb-f090890338d3",
    "changedFields": {
      "employee": {
        "firstName": "Robert",
        "lastName": "Johnson",
        "middleName": "William",
        "nickname": "Bob",
        "socialSecurityNumber": "987-65-4321",
        "telephoneNumber": "(555) 987-6543",
        "gender": "Male",
        "dateOfBirth": "1985-06-15",
        "address": {
          "streetAddress1": "789 Pine St",
          "streetAddress2": "Suite 100",
          "city": "Another City",
          "state": "TX",
          "zipCode": "67890",
          "country": "US"
        }
      }
    }
  }
}

I-9 expiring documents (`employee.upcomingExpiration`)

Sent 30 days before a document expires, or immediately upon submission if within 30 days.

{
  "eventKey": "employee.upcomingExpiration",
  "timestamp": "2025-12-22T16:07:41.128Z",
  "data": {
    "employerId": "12345-3fe3-7146-8ea6-123456sdfg",
    "employeeId": "0987654-d7ee-702f-92f3-123456lkjhgf",
    "submission": {
      "id": 1345,
      "documentationExpirationDate": "2025-12-24"
    }
  }
}

Employee restarted Form I-9 (`employee.i9Restarted`)

Sent when an employee restarts the Form I-9 process. Workflow

The employee begins completing Section 1.
The employee or an administrator restarts the Form I-9 process.
A new Form I-9 process is initiated.
The employee.i9Restarted webhook is sent.

NoteThis event does not include a submission object because a new submission has not yet been created. The new submission ID is included in the subsequent employee.section1Complete webhook after the employee completes Section 1.

{
  "eventKey": "employee.i9Restarted",
  "timestamp": "2026-07-13T14:12:53.117Z",
  "data": {
    "employerId": "019e4177-aabb-7722-a79f-9066b64a6b2c",
    "employeeId": "019f5bce-4108-79a6-9de7-a4b652d60d0e"
  }
}

Employee submitted form (`employee.section1Complete`)

Sent when the employee completes Section 1.

{
  "eventKey": "employee.section1Complete",
  "timestamp": "2025-12-22T15:50:37.925Z",
  "data": {
    "employerId": "12345-3fe3-7146-8ea6-123456sdfg",
    "employeeId": "0987654-d7ee-702f-92f3-123456lkjhgf",
    "submission": {
      "id": 1334
    }
  }
}

Employee submission rejected (`employee.submissionRejected`)

Sent when an administrator rejects an employee’s Form I-9 submission during the review process. Workflow

Employee completes Section 1.
An administrator reviews the submission and completes Section 2.
The administrator rejects the Form I-9 submission and provides a rejection reason.
The employee.submissionRejected webhook is sent.

{
  "eventKey": "employee.submissionRejected",
  "timestamp": "2026-05-27T00:41:28.476Z",
  "data": {
    "employerId": "019e4177-aabb-7722-a79f-91234567890",
    "employeeId": "019e41bb-2b38-795d-b32d-0987654321",
    "submission": {
      "id": 2729,
      "rejectionReason": "Document could not be verified."
    }
  }
}

Employee submission reverified (`employee.submissionReverified`)

Sent when a Form I-9 has been successfully reverified through Supplement B. Workflow

Employee has an existing completed Form I-9.
An administrator initiates the Supplement B reverification process.
The administrator reviews and re-examines the employee’s documentation as part of reverification.
The reverification is completed.
The employee.submissionReverified webhook is sent.

{
  "eventKey": "employee.submissionReverified",
  "timestamp": "2024-07-18T21:17:06.847Z",
  "data": {
    "employerId": "019e4177-aabb-7722-1234567890",
    "employeeId": "019e41bb-2b38-795d-b32d-0987654321",
    "submission": {
      "id": 2730
    }
  }
}

Authorized representative mismatch (`employee.i9AuthRepMismatch`)

Sent when an authorized representative identifies a mismatch while reviewing an employee’s documents during remote countersigning. Workflow

The employee is configured to use remote countersigning with an authorized representative.
The employee completes Section 1.
The authorized representative reviews the employee’s documents during the remote countersigning process.
The authorized representative indicates that the employee’s presented documents do not match the information entered in the Form I-9.
The employee.i9AuthRepMismatch webhook is sent.

{
  "eventKey": "employee.i9AuthRepMismatch",
  "timestamp": "2026-05-13T13:50:13.572-07:00",
  "data": {
    "employerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "employeeId": "12345678-abcd-1234-efgh-1234567890ab",
    "submission": {
      "id": 2500
    }
  }
}

E-Verify authentication result (`employer.everifyAuthenticationResult`)

Sent when E-Verify credentials are authenticated or revalidated.

{
  "eventKey": "employer.everifyAuthenticationResult",
  "timestamp": "2026-02-17T13:50:13.572-07:00",
  "data": {
    "employerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "everifyAuthenticated": true
  }
}

Configuration

Webhooks are configured at the employer level using the /employers POST endpoint. You can update the callback URL later using the /employers/{employerId} PATCH endpoint. When configured, you will receive all webhook event types.

Request

The webhook object contains the configuration for where webhook events will be delivered.

Sample Request

{
  "name": "Example Company",
  "federalEIN": "98-7654321",
  "timezone": "America/New_York",
  "address": {
    "streetAddress1": "14350 N 87 ST",
    "streetAddress2": "STE 310",
    "city": "Scottsdale",
    "state": "AZ",
    "zipCode": "85260"
  },
  "webhook": {
    "callbackUrl": "https://client-system.example.com/callbacks/i9",
    "failureNotificationEmail": "admin@example.com",
    "authentication": {
      "authType": "basic",
      "username": "webhook_user",
      "password": "webhook_password"
    }
  }
}

Webhook object fields

Element	Type	Description
`callbackUrl`	string	Endpoint in your system where Symmetry will send the webhook event. This should be a publicly accessible URL that can receive `POST` requests.
`failureNotificationEmail`	string	Email address to notify if a webhook request fails
`authentication`	object	Specifies how Symmetry should authenticate when sending the webhook request to your system. Supported types include: `none`, `basic`, `oauth2`.
`authentication.authType`	enum	Required. Configures the authentication scheme type to be used: `none`, `basic`, `oauth2`.
`authentication.username`	string	Username to be used for basic authentication.
`authentication.password`	string	Password to be used for basic authentication.
`authentication.oauth2ClientId`	string	Oauth2 client ID required if using Oauth2 authentication
`authentication.oauth2ClientSecret`	string	Oauth2 client secret, required if using Oauth2 authentication
`authentication.oauth2AuthServerUrl`	string	URL to the Oauth2 token authentication server, required if using Oauth2 authentication
`authentication.oauth2GrantType`	enum	OAuth 2.0 grant type. Required when using OAuth 2.0 authentication. Currently supports the `client_credentials` grant.
`authentication.oauth2AdditionalParameters`	object	Additional parameters to be provided to the Oauth2 token authentication server

For full employer configuration details, see Configure Employers.

Authentication

Symmetry supports multiple authentication schemes when sending webhook requests:

None – no authentication header is included
Basic – Authorization: Basic <base64(username:password)>
OAuth2 – Symmetry will request an access token and include it in the Authorization: Bearer <token> header

Authentication credentials are included in the request header when Symmetry sends webhook payloads to your system. This ensures secure delivery and proper endpoint validation.

If using OAuth2, ensure your token endpoint supports Client Credentials grant type.

Failure notifications

You can optionally configure a dedicated email address to receive notifications when webhook deliveries fail. Notifications are sent only after all retry attempts have been exhausted. To configure the notifications, specify the target email address within the failureNotificationEmail field in the webhook object when setting up or updating each employer.

​Events

​Sample payloads

​Form I-9 was countersigned (employee.i9Complete)

​E-Verify case details updated (employee.everifyCaseUpdate)

​Employee profile updated (employee.profileUpdated)

​I-9 expiring documents (employee.upcomingExpiration)

​Employee restarted Form I-9 (employee.i9Restarted)

​Employee submitted form (employee.section1Complete)

​Employee submission rejected (employee.submissionRejected)

​Employee submission reverified (employee.submissionReverified)

​Authorized representative mismatch (employee.i9AuthRepMismatch)

​E-Verify authentication result (employer.everifyAuthenticationResult)

​Configuration

​Request

​Webhook object fields

​Authentication

​Failure notifications

Events

Sample payloads

Form I-9 was countersigned (`employee.i9Complete`)

E-Verify case details updated (`employee.everifyCaseUpdate`)

Employee profile updated (`employee.profileUpdated`)

I-9 expiring documents (`employee.upcomingExpiration`)

Employee restarted Form I-9 (`employee.i9Restarted`)

Employee submitted form (`employee.section1Complete`)

Employee submission rejected (`employee.submissionRejected`)

Employee submission reverified (`employee.submissionReverified`)

Authorized representative mismatch (`employee.i9AuthRepMismatch`)

E-Verify authentication result (`employer.everifyAuthenticationResult`)

Configuration

Request

Webhook object fields

Authentication

Failure notifications