> ## Documentation Index > Fetch the complete documentation index at: https://docs.symmetry.com/llms.txt > Use this file to discover all available pages before exploring further. # Webhooks > Receive real-time Symmetry I-9 notifications via webhooks. Covers every event key and its payload, callback authentication, and failure notifications. 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 service** While 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](/i9/getting-started/retrieve-completed-data). ## Sample payloads ### Form I-9 was countersigned (`employee.i9Complete`) Sent when Section 2 is countersigned. ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "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** 1. The employee begins completing Section 1. 2. The employee or an administrator restarts the Form I-9 process. 3. A new Form I-9 process is initiated. 4. The `employee.i9Restarted` webhook is sent. **Note** This 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. ```json theme={null} { "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. ```json theme={null} { "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** 1. Employee completes Section 1. 2. An administrator reviews the submission and completes Section 2. 3. The administrator rejects the Form I-9 submission and provides a rejection reason. 4. The `employee.submissionRejected` webhook is sent. ```json theme={null} { "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** 1. Employee has an existing completed Form I-9. 2. An administrator initiates the [Supplement B reverification](/i9/remote-i-9/reverification-supplement-b) process. 3. The administrator reviews and re-examines the employee's documentation as part of reverification. 4. The reverification is completed. 5. The `employee.submissionReverified` webhook is sent. ```json theme={null} { "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** 1. The employee is configured to use [remote countersigning with an authorized representative](/i9/remote-i-9/authorized-representatives). 2. The employee completes Section 1. 3. The authorized representative reviews the employee's documents during the remote countersigning process. 4. The authorized representative indicates that the employee's presented documents do not match the information entered in the Form I-9. 5. The `employee.i9AuthRepMismatch` webhook is sent. ```json theme={null} { "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. ```json theme={null} { "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. ```json Sample Request theme={null} { "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](/i9/getting-started/configure-employers). ## Authentication Symmetry supports multiple authentication schemes when sending webhook requests: * None – no authentication header is included * Basic – `Authorization: Basic ` * OAuth2 – Symmetry will request an access token and include it in the `Authorization: Bearer ` 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.