> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.middesk.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.middesk.com/_mcp/server. # Configure webhooks for entity management > Receive entity management webhook events for registrations, information requests, item changes, and mail. Configure [webhooks](/build/webhooks) to receive notifications when registrations, information requests, item changes, and mail are created or updated. ## Subscribe to events You can subscribe to these event types: registration requests, jurisdiction registrations, information requests, item changes, and mail. ### Registration request events Receive real-time updates about registration requests created via the [POST /registration\_requests endpoint](/api-reference/entity-management/registration-requests/create-a-registration-request). * `registration_request.submitted` sends when a state tax registration request is submitted by the employer. * `registration_request.updated` sends when a Tax Registration Item created by that submitted registration request is completed and its Tax IDs are available. Multiple updates are possible as items complete over time. Use these example payloads to notify your systems of any changes to a registration request. **`registration_request.submitted`** ```json title="registration_request.submitted" { "account_id": "your-middesk-account-id", "created_at": "2023-02-08T18:04:43.939Z", "data" : { "object": { "object": "registration_request", "id": "middesk-registration-request-id", "state": "CA", "company_id": "middesk-child-company-id", "created_at": "2023-02-02T17:00:22Z", "submitted_at": "2023-02-08T18:04:43Z", "status": "submitted", "items": [ { "agency": "Employment Development Department (EDD)", "label": "SUI Rate", "state": "CA", "updated_at": "2023-02-08T18:04:43Z", "value": null }, { "agency": "Employment Development Department (EDD)", "label": "EDD number", "state": "CA", "updated_at": "2023-02-08T18:04:43Z", "value": null } ] } }, "id": "middesk-event-id", "object": "event", "type": "registration_request.submitted" } ``` **`registration_request.updated`** ```json title="registration_request.updated" { "account_id": "your-middesk-account-id", "created_at": "2023-02-08T18:04:43.939Z", "data" : { "object": { "object": "registration_request", "id": "middesk-registration-request-id", "state": "CA", "company_id": "middesk-child-company-id", "created_at": "2023-02-02T17:00:22Z", "submitted_at": "2023-02-08T17:00:43Z", "status": "completed", "items": [ { "agency": "Employment Development Department (EDD)", "label": "SUI Rate", "state": "CA", "updated_at": "2023-02-08T18:04:43Z", "value": "12" }, { "agency": "Employment Development Department (EDD)", "label": "EDD number", "state": "CA", "updated_at": "2023-02-08T17:00:43Z", "value": "10201" } ] } }, "id": "middesk-event-id", "object": "event", "type": "registration_request.updated" } ``` Understand the status of your jurisdiction registration requests. | Status | Description | | ----------- | ----------------------------------------------------------------------------------------------- | | `pending` | registration request has not yet been submitted by employer. | | `submitted` | registration request has been submitted but not all Tax Registration Items are completed. | | `completed` | registration request has been submitted and all Tax Registration Items are marked as completed. | ### Jurisdiction registrations * `agent_jurisdiction_registration.created` sends when a jurisdiction registration is created by Middesk. * `agent_jurisdiction_registration.updated` sends whenever the status of a jurisdiction registration is updated by Middesk. Use these example payloads to notify your systems of any changes to a jurisdiction registration. **`agent_jurisdiction_registration.created`** ```json title="agent_jurisdiction_registration.created" { "id": "5dcf54c3-7b81-43ad-94ac-70394fed291b", "company_id": "dbb0f373-b744-465e-941e-ab76d4194a86", "external_id": null, "status": "middesk_processing", "tax_type": "FLI", "jurisdiction_name": "Connecticut Paid Leave", "jurisdiction_slug": "connecticut_paid_leave", "created_at": "2025-08-13T18:21:36Z", "updated_at": "2025-08-13T18:21:36Z", "submitted_at": null, "completed_at": null, "status_updated_at": "2025-08-13T18:21:36Z", "blocked_by": null, "blocked_until": null, "transfer": false, "items": [ { "agency": "Connecticut Paid Family Leave Authority", "label": "CT PFML Account Number", "key": "ct_fli_account_number", "value": null, "state": "CT", "status": "open", "updated_at": "2025-08-13T18:21:36Z" } ], "registration_request_id": "e5085880-fd34-4a8d-a91c-30b6d44ac6e5", "object": "jurisdiction_registration" } ``` **`agent_jurisdiction_registration.updated`** ```json title="agent_jurisdiction_registration.updated" { "id": "5dcf54c3-7b81-43ad-94ac-70394fed291b", "company_id": "dbb0f373-b744-465e-941e-ab76d4194a86", "external_id": null, "status": "completed", "tax_type": "FLI", "jurisdiction_name": "Connecticut Paid Leave", "jurisdiction_slug": "connecticut_paid_leave", "created_at": "2025-08-13T18:21:36Z", "updated_at": "2025-08-13T19:21:36Z", "submitted_at": null, "completed_at": null, "status_updated_at": "2025-08-13T18:21:36Z", "blocked_by": null, "blocked_until": null, "transfer": false, "items": [ { "agency": "Connecticut Paid Family Leave Authority", "label": "CT PFML Account Number", "key": "ct_fli_account_number", "value": "456-123-7890", "state": "CT", "status": "open", "updated_at": "2025-08-13T19:21:36Z" } ], "registration_request_id": "e5085880-fd34-4a8d-a91c-30b6d44ac6e5", "object": "jurisdiction_registration" } ``` Understand the status of your jurisdiction registration requests. | Status | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `information_requested` | Jurisdiction registration requires additional information from the customer before processing can continue. | | `blocked_by_government` | Jurisdiction registration is blocked by government requirements (for example, waiting for hire date, payroll date, or liability date). | | `middesk_processing` | Jurisdiction registration is being processed by Middesk staff. | | `government_processing` | Jurisdiction registration has been submitted to the government and is being processed by the government. | | `completed` | Jurisdiction registration has been completed and deliverables (like Account Number, UI Account number, and UI Tax rates) are available. | | `duplicate` | Jurisdiction registration and corresponding deliverables were marked as duplicate since the company's information was already registered with the state or local government. | | `unmanaged` | Jurisdiction registration is not managed by Middesk. | | `not_required` | Jurisdiction registration is deemed by the government as not required for this business in this jurisdiction. | ### Information request events * `agent_info_request.created` sends when an information request is created. The link to the web form for the information request is provided in the url property. * `agent_info_request.updated` sends when an information request is updated. * `agent_info_request.voided` sends when an information request is voided. A voided information request no longer needs action. Use these example payloads to notify your systems of any changes to an information request. **`agent_info_request.created`** ```json title="agent_info_request.created" { "account_id": "your-middesk-account-id", "created_at": "2024-11-27T18:04:43.939Z", "id": "middesk-event-id", "object": "event", "type": "agent_info_request.created", "data" : { "object": "agent_exception", "id": "12de5aa8-ff34-4aae-9b7a-dd776d200eba", "created_at": "2024-12-19T15:52:49.324Z", "updated_at": "2024-12-19T15:52:49.324Z", "completed_at": null, "voided_at": null, "url": "https://agent.middesk.com/info_requests/12de5aa8-ff34-4aae-9b7a-dd776d200eba", "owner": { "id": "5c94b5d0-d103-403e-befc-879bee38fc4b", "state": "CA", "owner_type": "Agent::TaxRegistration", "application_type": "new_registration", "registration": true, "legal_name": "Middesk", "company_id": "259fc2fa-ae6d-4b73-9610-ba500e274078", "provider_company_id": null, "external_id": "808b33dd-3755-42c1-aeb6-5710b5c91d47" }, "company": { "id": "259fc2fa-ae6d-4b73-9610-ba500e274078", "legal_name": "Middesk", "provider_company_id": null, "external_id": "808b33dd-3755-42c1-aeb6-5710b5c91d47" }, "account": { "id": "a8caeb8d-67a7-4d9b-93e3-72b25dfa136e", "name": "Heaney, Kertzmann and Johns", "slug": "dolor-in", "parent_account": null } } } ``` **`agent_info_request.updated`** ```json title="agent_info_request.updated" { "account_id": "your-middesk-account-id", "created_at": "2024-11-27T18:04:43.939Z", "id": "middesk-event-id", "object": "event", "type": "agent_info_request.updated", "data" : { "object": "agent_exception", "id": "12de5aa8-ff34-4aae-9b7a-dd776d200eba", "created_at": "2024-12-19T15:52:49.324Z", "updated_at": "2024-12-20T15:52:49.324Z", "completed_at": "2024-12-20T15:52:49.324Z", "voided_at": null, "url": "https://agent.middesk.com/info_requests/12de5aa8-ff34-4aae-9b7a-dd776d200eba", "owner": { "id": "5c94b5d0-d103-403e-befc-879bee38fc4b", "state": "CA", "owner_type": "Agent::TaxRegistration", "application_type": "new_registration", "registration": true, "legal_name": "Middesk", "company_id": "259fc2fa-ae6d-4b73-9610-ba500e274078", "provider_company_id": null, "external_id": "808b33dd-3755-42c1-aeb6-5710b5c91d47" }, "company": { "id": "259fc2fa-ae6d-4b73-9610-ba500e274078", "legal_name": "Middesk", "provider_company_id": null, "external_id": "808b33dd-3755-42c1-aeb6-5710b5c91d47" }, "account": { "id": "a8caeb8d-67a7-4d9b-93e3-72b25dfa136e", "name": "Heaney, Kertzmann and Johns", "slug": "dolor-in", "parent_account": null } } } ``` **`agent_info_request.voided`** ```json title="agent_info_request.voided" { "account_id": "your-middesk-account-id", "created_at": "2024-11-27T18:04:43.939Z", "id": "middesk-event-id", "object": "event", "type": "agent_info_request.voided", "data" : { "object": "agent_exception", "id": "12de5aa8-ff34-4aae-9b7a-dd776d200eba", "created_at": "2024-12-19T15:52:49.324Z", "updated_at": "2024-12-19T15:52:49.324Z", "completed_at": null, "voided_at": "2024-12-20T15:52:49.324Z", "url": "https://agent.middesk.com/info_requests/12de5aa8-ff34-4aae-9b7a-dd776d200eba", "owner": { "id": "5c94b5d0-d103-403e-befc-879bee38fc4b", "state": "CA", "owner_type": "Agent::TaxRegistration", "application_type": "new_registration", "registration": true, "legal_name": "Middesk", "company_id": "259fc2fa-ae6d-4b73-9610-ba500e274078", "provider_company_id": null, "external_id": "808b33dd-3755-42c1-aeb6-5710b5c91d47" }, "company": { "id": "259fc2fa-ae6d-4b73-9610-ba500e274078", "legal_name": "Middesk", "provider_company_id": null, "external_id": "808b33dd-3755-42c1-aeb6-5710b5c91d47" }, "account": { "id": "a8caeb8d-67a7-4d9b-93e3-72b25dfa136e", "name": "Heaney, Kertzmann and Johns", "slug": "dolor-in", "parent_account": null } } } ``` ### Item change events * `agent_item_change.created` sends when an item change is created. * `agent_item_change.updated` sends when an item change is updated. This includes when it is applied to the existing tax registration item. Use these example payloads to notify your systems of any changes to an item. **`agent_item_change.created`** ```json title="agent_item_change.created" { "account_id": "your-middesk-account-id", "created_at": "2024-12-19T19:10:11.859Z", "id": "middesk-event-id", "object": "event", "type": "agent_item_change.created", "data" : { "object": "agent_item_change", "id": "481e5c1b-228a-4427-92d9-3835973caaac", "created_at": "2024-12-19T19:10:11.859Z", "effective_at": "2025-01-19", "applied_at": null, "from_value": "3.4%", "to_value": "3.6%", "tax_registration_item": { "id": "64e01f8a-f1d8-4cb9-9f54-7feef4eb979f", "agency": "Employment Development Department (EDD)", "key": "ca_sui_rate", "label": "SUI Rate", "requirement_type": "state_unemployment_insurance", "status": "active", "value": "3.4%", "state": "CA" }, "tax_registration": { "id": "88e7f433-3a1b-4a26-846f-bdf1e3d2a4bc", "state": "CA", "tax_types": [ "state_unemployment_insurance", "state_tax_withholdings" ], "status": "active" }, "company": { "legal_name": "Middesk, Inc.", "dba_name": "Middesk", "provider_company_id": null, "external_id": "9bdbbac4-1b83-4f92-9272-60a82b41b0da", "id": "0e7c8bd5-8a9e-481b-af69-fe6f99c69df5" }, "account": { "id": "0dd06e4d-57bc-4977-b596-f8a277f42b75", "name": "Mertz, Fay and Schoen", "slug": "repellat_aut", "parent_account": null } } } ``` **`agent_item_change.updated`** ```json title="agent_item_change.updated" { "account_id": "your-middesk-account-id", "created_at": "2024-12-20T19:10:11.859Z", "id": "middesk-event-id", "object": "event", "type": "agent_item_change.updated", "data" : { "object": "agent_item_change", "id": "481e5c1b-228a-4427-92d9-3835973caaac", "created_at": "2024-12-20T19:10:11.859Z", "effective_at": "2024-12-20", "applied_at": "2024-12-20T19:10:11.859Z", "from_value": "3.4%", "to_value": "3.6%", "tax_registration_item": { "id": "64e01f8a-f1d8-4cb9-9f54-7feef4eb979f", "agency": "Employment Development Department (EDD)", "key": "ca_sui_rate", "label": "SUI Rate", "requirement_type": "state_unemployment_insurance", "status": "active", "value": "3.6%", "state": "CA" }, "tax_registration": { "id": "88e7f433-3a1b-4a26-846f-bdf1e3d2a4bc", "state": "CA", "tax_types": [ "state_unemployment_insurance", "state_tax_withholdings" ], "status": "active" }, "company": { "legal_name": "Middesk, Inc.", "dba_name": "Middesk", "provider_company_id": null, "external_id": "9bdbbac4-1b83-4f92-9272-60a82b41b0da", "id": "0e7c8bd5-8a9e-481b-af69-fe6f99c69df5" }, "account": { "id": "0dd06e4d-57bc-4977-b596-f8a277f42b75", "name": "Mertz, Fay and Schoen", "slug": "repellat_aut", "parent_account": null } } } ``` ### Mail * `agent_mail.available` sends when a piece of mail is newly available in Middesk. Use this example payload to notify your systems of mail received by Middesk. **`agent_mail.available`** ```json title="agent_mail.available" { "account_id": "your-middesk-account-id", "created_at": "2024-11-27T18:04:43.939Z", "id": "middesk-event-id", "object": "event", "type": "agent_mail.available", "data" : { "object": "agent_mail", "id": "1df541f1-fee9-4612-be6b-c9dd11b557b9", "sender_name": "Department of Revenue", "recipient_name": "Your company name", "agency_name": "Department of Revenue", "tag_names": ["no_action_required"], "state": "CA", "owner": { "type": "tax_registration", "id": "d7376440-a647-4d62-bf8b-111eb924f355" }, "source": { "type": "tax_registration", "id": "d7376440-a647-4d62-bf8b-111eb924f355" }, "company": { "legal_name": "Middesk", "dba_name": "Deskmid", "provider_company_id": null, "external_id": "b4901bfe-4777-4c6a-86e8-a6b43c6df904" }, "account": { "id": "13a25067-a804-4f1c-a9f6-d131f652df40", "name": "O'Reilly-Robel", "slug": "possimus_maxime", "parent_account": { "id": "a7be256c-25e6-474c-ac58-7f9dc32bc0ff", "name": "Stoltenberg, Klocko and Rosenbaum", "slug": "voluptate-et" } }, "document_url": "https://storage.googleapis.com/middesk/abc123" } } ``` > **Get a demo** > > Contact your account manager or [contact sales](https://www.middesk.com/contact-sales) to inquire about access.