Product Guides
Login for full accessGet a demo

Webhooks

Suggest Edits

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.

eventKeyEventDescription
employee.i9CompleteForm I-9 was countersignedNotifies you when an employee's I-9 is complete and Section 2 is countersigned.
employee.everifyCaseUpdateE-Verify case details updatedTriggered when an employee’s E-Verify case is updated. Use this to prompt internal review or next steps.
employee.profileUpdatedEmployee profile updatedNotifies you when an employee's profile is updated (for example, social security number is added). It is not triggered when the employee is created.
employee.upcomingExpirationI-9 expiring documentsTriggers 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.section1CompleteEmployee submitted formFires when an employee completes Section 1, allowing you to prompt administrative review.
employee.submissionRejectedEmployee submission rejectedNotifies you when an employer rejects an employee's Form I-9 submission during the review process. Includes the rejection reason.
employee.submissionReverifiedEmployee submission reverifiedNotifies you when a Form I-9 has been successfully reverified through Supplement B.
employee.i9AuthRepMismatchAuthorized representative mismatchTriggered when an authorized representative identifies a mismatch while reviewing an employee’s Form I-9 documents during remote countersigning.
employer.everifyAuthenticationResultE-Verify authentication resultNotifies 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.

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 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.

{
  "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": "[email protected]",
    "authentication": {
      "authType": "basic",
      "username": "webhook_user",
      "password": "webhook_password"
    }
  }
}

Webhook object fields

ElementTypeDescription
callbackUrlstringEndpoint in your system where Symmetry will send the webhook event. This should be a publicly accessible URL that can receive POST requests.
failureNotificationEmailstringEmail address to notify if a webhook request fails
authenticationobjectSpecifies how Symmetry should authenticate when sending the webhook request to your system. Supported types include: none, basic, oauth2.
authentication.authTypeenumRequired. Configures the authentication scheme type to be used: none, basic, oauth2.
authentication.usernamestringUsername to be used for basic authentication.
authentication.passwordstringPassword to be used for basic authentication.
authentication.oauth2ClientIdstringOauth2 client ID required if using Oauth2 authentication
authentication.oauth2ClientSecretstringOauth2 client secret, required if using Oauth2 authentication
authentication.oauth2AuthServerUrlstringURL to the Oauth2 token authentication server, required if using Oauth2 authentication
authentication.oauth2GrantTypeenumOAuth 2.0 grant type. Required when using OAuth 2.0 authentication. Currently supports the client_credentials grant.
authentication.oauth2AdditionalParametersobjectAdditional 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.

Jump to top