Create webhooks that trigger on every subgraph entity change
When you need to execute code or update a backend based on webhooks, you can use subgraph webhooks to send a payload to an HTTP server for every subgraph entity change.
See the webhook quick start for more a step by step guide in using this feature.
If you’re using this feature to push and sync data to a database, consider using mirror to sync subgraph data to your backend with guaranteed data delivery.
When a subgraph handler does something like entity.save()
, an update is written to an intermediate db which powers the subgraph API. This update is interpreted by a real-time watcher and set to your webhook handler, with an UPDATE
, INSERT
, or DELETE
operation.
If you’re tracking an immutable entity (as in one that does not get updated), then this section is not applicable.
Subgraphs store all versions of entities, each with a block_range
column which shows it’s valid for each block range. This allows you to distinguish between an entity changing vs a change being rolled-back due to blockchain reorgs.
Updates (when an existing entity’s .save()
is called) in a subgraph entity system is denoted as a new version row being created, with a corresponding update on the last version’s row.
There is an entity with the id: 1
created at block 1. A webhook will fire:
In the following block number 2, the entity is updated again.
Two webhooks are then fired. One to track the new version being created,
Another to track the previous version being updated,
Similar to updates, entity removal in a subgraph mapping handler simply involves updating the block range associated with the entity. There is no actual row deletion outside of blockchain reorganizations.
Entities with a “closed” block range (e.g., [123, 1234)) can be removed if they aren’t needed for historical state.
It is recommended to maintain a “deleted_at” and “updated_at” timestamp in the local representation of the entity and keep them updated accordingly.
If your goal is to track the latest state of an entity for the most recent block, when you see any CREATE
or UPDATE
webhook, you can do an upsert
in your database for the id
. The id
always tracks a unique entity. The vid
in the payload denotes the version of the id
, where the highest vid
is the latest version.
It is important to note that there is no guarantee of ordering between the insert and update operation webhooks, as they are part of the same atomic operation when a subgraph mapping handler runs.
An effective strategy involves utilizing the “deleted_at” and “updated_at” flags in the local representation to manage any potential race conditions.
To create a new webhook for a subgraph entity:
Optionally, you can also add --secret "some-secret"
to have control over the secret you can use to identify valid traffic from goldsky.
To see a list of already configured webhooks:
If you no longer need a webhook, you can delete it with the following command:
The webhook payload is a JSON object with the following fields:
Create webhooks that trigger on every subgraph entity change
When you need to execute code or update a backend based on webhooks, you can use subgraph webhooks to send a payload to an HTTP server for every subgraph entity change.
See the webhook quick start for more a step by step guide in using this feature.
If you’re using this feature to push and sync data to a database, consider using mirror to sync subgraph data to your backend with guaranteed data delivery.
When a subgraph handler does something like entity.save()
, an update is written to an intermediate db which powers the subgraph API. This update is interpreted by a real-time watcher and set to your webhook handler, with an UPDATE
, INSERT
, or DELETE
operation.
If you’re tracking an immutable entity (as in one that does not get updated), then this section is not applicable.
Subgraphs store all versions of entities, each with a block_range
column which shows it’s valid for each block range. This allows you to distinguish between an entity changing vs a change being rolled-back due to blockchain reorgs.
Updates (when an existing entity’s .save()
is called) in a subgraph entity system is denoted as a new version row being created, with a corresponding update on the last version’s row.
There is an entity with the id: 1
created at block 1. A webhook will fire:
In the following block number 2, the entity is updated again.
Two webhooks are then fired. One to track the new version being created,
Another to track the previous version being updated,
Similar to updates, entity removal in a subgraph mapping handler simply involves updating the block range associated with the entity. There is no actual row deletion outside of blockchain reorganizations.
Entities with a “closed” block range (e.g., [123, 1234)) can be removed if they aren’t needed for historical state.
It is recommended to maintain a “deleted_at” and “updated_at” timestamp in the local representation of the entity and keep them updated accordingly.
If your goal is to track the latest state of an entity for the most recent block, when you see any CREATE
or UPDATE
webhook, you can do an upsert
in your database for the id
. The id
always tracks a unique entity. The vid
in the payload denotes the version of the id
, where the highest vid
is the latest version.
It is important to note that there is no guarantee of ordering between the insert and update operation webhooks, as they are part of the same atomic operation when a subgraph mapping handler runs.
An effective strategy involves utilizing the “deleted_at” and “updated_at” flags in the local representation to manage any potential race conditions.
To create a new webhook for a subgraph entity:
Optionally, you can also add --secret "some-secret"
to have control over the secret you can use to identify valid traffic from goldsky.
To see a list of already configured webhooks:
If you no longer need a webhook, you can delete it with the following command:
The webhook payload is a JSON object with the following fields: