​
Configuring your Webhook URL

You can set up your Webhook URL in the Paragon dashboard to start receiving events about your Syncs.

Navigate to the Syncs page in the dashboard to set your Webhook URL for a specific Paragon project:

Your Webhook URL must respond to POST requests with a 2xx HTTP status in a timely manner. If your webhook fails to respond repeatedly, we may disable your webhook.

​
Receiving Webhook Events

All webhook events will be sent to your configured Webhook URL as a POST request.

Each webhook event will include the following standard properties to identify the related Sync and User:

{
	"event": "[event type]",
	"sync": "[integration name]",
	"syncInstanceId": "[ID of Sync]",
	"user": {
		"id": "[ID of Connected User]"
	}
}

​
Event Types

The full list of possible event type values are as follows:

  • sync_complete
  • sync_errored
  • record_created
  • record_updated
  • record_deleted
  • record_errored

​
sync_complete

This event is sent when an Initial Sync has completed successfully.

Example payload
{
  "event": "sync_complete",
  "syncInstanceId": "163a345e-2dd4-51ff-bcf5-7667de564bb0",
  "sync": "googledrive",
  "user": {
    "id": "user_01JH448D13EX2BE1SC1GXVT05R"
  },
  "data": {
    "model": "files",
    "syncedAt": "2025-07-07T19:00:00.000Z",
    "numRecords": 1000
  }
}

​
sync_errored

This event is sent when a Sync has failed and cannot continue. After this event is sent, the Sync status field will be set to ERRORED.

Example payload
{
  "event": "sync_errored",
  "syncInstanceId": "f543fd08-5d36-56d7-bd5e-8306e82acb16",
  "sync": "googledrive",
  "user": {
    "id": "user_01JH448D13EX2BE1SC1GXVT05R"
  },
  "error": {
    "message": "Credentials are no longer valid. Please re-authenticate the user's Google Drive account."
  }
}

​
record_created

This event is sent when a Sync has discovered a new record (determined by a permanent ID or path available in the integration provider) during its Incremental Sync.

Create events do not provide any record data as a part of the event payload, but you can use the Get Synced Record endpoint to get the latest data.

Example payload
{
  "event": "record_created",
  "syncInstanceId": "163a345e-2dd4-51ff-bcf5-7667de564bb0",
  "sync": "googledrive",
  "user": {
    "id": "user_01JH448D13EX2BE1SC1GXVT05R"
  },
  "data": {
    "recordId": "3ce16e33-0163-564d-98ce-99b0a25ab375",
    "model": "files"
  }
}

​
record_updated

This event is sent when a Sync has discovered an update to an existing record during its Incremental Sync.

Update events do not provide any record data as a part of the event payload, but you can use the Get Synced Record endpoint to get the latest data.

Example payload
{
  "event": "record_updated",
  "syncInstanceId": "163a345e-2dd4-51ff-bcf5-7667de564bb0",
  "sync": "googledrive",
  "user": {
    "id": "user_01JH448D13EX2BE1SC1GXVT05R"
  },
  "data": {
    "recordId": "3ce16e33-0163-564d-98ce-99b0a25ab375",
    "model": "files"
  }
}

​
record_deleted

This event is sent when a Sync has discovered that a record has been deleted or is otherwise unavailable to the connected account (for example, the record’s access has been revoked from your user).

When records are deleted, the contents of their metadata are removed from the Sync, and you can no longer retrieve the synced object or its associated file data. However, the Pull Synced Records endpoint will provide a sparse entry with the id and external_id property for visibility on the deletion.

These events are sent after a successful Periodic Full Sync.

Example payload
{
  "event": "record_deleted",
  "syncInstanceId": "0df4921d-0ac4-5c90-b30e-7a9da9c2d02f",
  "sync": "googledrive",
  "user": {
    "id": "user_01JH448D13EX2BE1SC1GXVT05R"
  },
  "data": {
	"model": "files",
	"recordId": "3ce16e33-0163-564d-98ce-99b0a25ab375"
  }
}

​
record_errored

This event is sent when a Sync has encountered an error while processing a record (for example, fetching permission data for this record). This event does not affect the Sync’s status field, and the Sync will continue processing other records.

Example payload
{
  "event": "record_errored",
  "syncInstanceId": "0df4921d-0ac4-5c90-b30e-7a9da9c2d02f",
  "sync": "googledrive",
  "user": {
    "id": "user_01JH448D13EX2BE1SC1GXVT05R"
  },
  "error": {
    "message": "Request failed with status code 404",
    "recordId": "68c3e715-b466-544f-ba2a-165973d85a58",
    "model": "files"
  }
}