Webhook CRM snapshots API

The snapshots API allows you to trigger snapshots of CRM objects for specific points in time. To use this API, ensure your client credentials token was generated with the developer.webhooks_journal.snapshots.write scope specified.

Create CRM object snapshots

To create snapshots for multiple CRM objects in a single batch request, make a POST request to /webhooks-journal/snapshots/2026-03/crm. In the request body, include the snapshotRequests property with the objects you want to snapshot. The available properties for this endpoint are listed in the table below. All fields are required.

Field	Type	Description
`snapshotRequests`	Array	A list of snapshot request objects.
`portalId`	Number	The ID of the HubSpot account where the object exists.
`objectId`	Number	The ID of the CRM object to snapshot.
`objectTypeId`	String	Object type identifier (e.g., `"0-1"` for contacts).
`properties`	Array	Array of property names to include in the snapshot.

{
  "snapshotRequests": [
    {
      "portalId": 12345,
      "objectId": 1001,
      "objectTypeId": "0-1",
      "properties": ["email", "firstname", "lastname", "phone"]
    },
    {
      "portalId": 12345,
      "objectId": 1002,
      "objectTypeId": "0-1",
      "properties": ["email", "company"]
    }
  ]
}

curl -X POST \
  https://api.hubapi.com/webhooks-journal/snapshots/2026-03/crm \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshotRequests": [
      {
        "portalId": 12345,
        "objectId": 1001,
        "objectTypeId": "0-1",
        "properties": ["email", "firstname", "lastname", "phone"]
      },
      {
        "portalId": 12345,
        "objectId": 1002,
        "objectTypeId": "0-1",
        "properties": ["email", "company"]
      }
    ]
  }'

A successful request will return status tracking IDs for each requested snapshot:

{
  "snapshotResponses": [
    {
      "portalId": 12345,
      "objectId": 1001,
      "objectTypeId": "0-1",
      "snapshotStatusId": "550e8400-e29b-41d4-a716-446655440000"
    },
    {
      "portalId": 12345,
      "objectId": 1002,
      "objectTypeId": "0-1",
      "snapshotStatusId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
    }
  ]
}

You can then use the snapshotStatusId from each entry to poll for processing status, as detailed in the section below.

Get snapshot status

Snapshot processing is asynchronous: when you create a snapshot, you receive a snapshotStatusId rather than an immediate result. Poll the status endpoint until status reaches a terminal state (SUCCESS, FAILED, or EXPIRED). See Polling behavior and 404 responses below for guidance on handling the brief window before a status record becomes available. To get the status of a snapshot, make a GET request to /webhooks-journal/snapshots/2026-03/crm/status/{snapshotStatusId}. For example, assuming a snapshotStatusId of 550e8400-e29b-41d4-a716-446655440000, the corresponding cURL command would be:

curl -X GET \
  https://api.hubapi.com/webhooks-journal/snapshots/2026-03/crm/status/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The response will resemble the following:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "SUCCESS",
  "initiatedAt": 1704067200000,
  "completedAt": 1704067215000
}

Property	Type	Description
`id`	String	The snapshot status ID.
`status`	String	Current processing status. Possible values are: `PENDING`: the snapshot has been accepted and is queued for processing. `IN_PROGRESS`: the snapshot is actively being processed. `SUCCESS`: the internal processing of the snapshot completed without errors. The snapshot may appear in the journal a few seconds after `SUCCESS` is set. `FAILED`: processing encountered an error. Check `errorCode` for the reason. `EXPIRED`: the snapshot was not processed within the allowed window and has been discarded.
`errorCode`	String	Machine-readable failure reason. Present only when `status` is `FAILED`. Possible values are: `TIMEOUT`: processing exceeded the allowed time limit. `VALIDATION_ERROR`: the snapshot request contained invalid data (e.g., the object or requested properties do not exist). `INTERNAL_ERROR`: an unexpected internal error occurred during processing. `PERMISSION_DENIED`: the app does not have permission to access the requested object or properties.
`message`	String	Human-readable detail about the status. Present on failure.
`initiatedAt`	Number	Unix timestamp (milliseconds) when the snapshot was requested.
`completedAt`	Number	Unix timestamp (milliseconds) when processing reached a terminal state. Absent while still pending or in progress.

Polling behavior and 404 responses

Snapshot status records are created asynchronously after the snapshot request is accepted. After creating a snapshot, there is a brief window during which polling for its status may return 404 Not Found. This is expected, since the status record is propagated across regions and will be available to retrieve after a short delay.

A 404 does not mean the snapshot itself failed. The underlying snapshot processing proceeds independently of status record creation. If a status record never appears, check your journal directly, as the snapshot may have completed successfully regardless.

The recommended polling strategy is:

After creating snapshots, store each snapshotStatusId.
Poll GET /webhooks-journal/snapshots/2026-03/crm/status/{snapshotStatusId} with exponential backoff (e.g., starting at 1 seconds, capped at 30 seconds).
On 404, treat it as “not yet available” and retry.
Stop polling when status is SUCCESS, FAILED, or EXPIRED.
Enforce a maximum polling duration or attempt count (e.g., 10 minutes / 20 attempts) to avoid infinite loops.
If the terminal state is never reached within that window, check your journal directly.

​Create CRM object snapshots

​Get snapshot status

​Polling behavior and 404 responses

Create CRM object snapshots

Get snapshot status

Polling behavior and 404 responses