This guide defines key terms related to BlockMark Registry's webhook system, helping you understand and configure webhooks effectively.
The webhook payload is the JSON data sent by BlockMark Registry to your webhook endpoint. It always includes an event key, which specifies the type of webhook (e.g., issued_certificate.created), and a data key, which contains the event-specific data. This consistent structure ensures your endpoint can reliably parse the event type and associated information for processing.
The webhook secret is a unique key assigned to your organisation account. BlockMark Registry uses this secret to generate a HMAC (Hash-based Message Authentication Code) using the SHA256 algorithm. The HMAC is converted to a hexadecimal string (hex) and included in the X-Token header of every webhook request.
To ensure security, always verify the X-Token header to confirm the request's authenticity. For details on verification, refer to the Verifying Webhook Requests guide.
A webhook is an event-driven notification triggered by specific actions in Blockmark Registry. Every webhook is filtered by a related object: certificate webhooks are filtered by certification scheme, watchlist webhooks by watchlist. You must select at least one related object, and the webhook only fires for events matching your selection.
The following webhooks are currently available.
| Webhook Name | Description |
|---|---|
| issued_certificate.created | Triggered when you issue a certificate. Filtered by certification scheme. |
| issued_certificate.updated | Triggered when a certificate you issued is updated. Filtered by certification scheme. Only fires for changes to the fields listed below. |
| issued_certificate.organisation_updated | Triggered when an organisation that holds a certificate you issued changes its name or its identifier (country, type, number). Filtered by certification scheme. The payload carries the new organisation details plus the IDs of your affected certificates. |
issued_certificate.updated fires on changes to these fields:
Note that custom_fields and custom_notes are included in the payload but do not trigger the webhook on their own.
These webhooks are filtered by watchlist. Certificate events are also subject to the watchlist's own certification scheme filter: if the watchlist has a certification scheme filter set, only certificates in those certification schemes fire the webhook, and an empty filter passes every scheme. Private (hidden) and test certificates never fire watchlist webhooks.
| Webhook Name | Description |
|---|---|
| watchlist.certificate_created | Triggered when a new public certificate is issued to someone in your watchlist. |
| watchlist.certificate_updated | Triggered when a public certificate belonging to someone in your watchlist changes its status, name_on_certificate, start_time, or finish_time. |
| watchlist.watch_object_created | Triggered when an object is added to one of your watchlists. |
| watchlist.watch_object_deleted | Triggered when an object is removed from one of your watchlists. |
A webhook endpoint is the URL where BlockMark Registry sends webhook notifications. This is typically a REST API endpoint configured to receive and process data from the subscribed webhook(s).
Endpoints must use HTTPS, and they must resolve to a public address. URLs pointing at private or internal network addresses are rejected.
An endpoint also has to be verified before anything is delivered to it. Webhooks cannot be activated or resumed while their endpoint is unverified, and if you point a group at a different endpoint that is not yet verified, its active webhooks are paused: delivery stops, but the backlog is kept and new events keep queuing. Verify the endpoint, then resume.
Each webhook has a status, which is your delivery intent:
Inactive: Not delivering, and no events are retained.
Active: Delivering normally.
Paused: Not delivering, but events are retained and delivered when you resume.
Separately, a webhook can be marked broken. This is delivery health, not intent. After 12 failed attempts, BlockMark Registry stops retrying and flags the webhook as broken. The two are independent: a webhook can be Active and broken at the same time.
A webhook group is a collection of webhooks with shared settings. It includes:
Endpoint: The URL where webhooks are sent. You can select an existing endpoint or add a new one.
Name: A descriptive name to identify the webhook group.
Webhooks: The specific webhooks you want to receive, along with the related objects (certification schemes or watchlists) that filter events.
Webhook groups are managed in the Webhooks section of the Organisation Settings page. Each group has a menu with the following actions:
Activate all: Activates every inactive webhook in the group. Requires a verified endpoint.
Pause all: Pauses every active webhook in the group. Delivery stops, and the backlog is kept.
Resume all: Resumes every paused webhook in the group and delivers its held backlog. Requires a verified endpoint.
Deactivate all: Deactivates every active or paused webhook in the group and discards each one's backlog.
Edit: Allows modification of the group's settings, such as changing the endpoint.
View Attempt Logs: Displays the Attempts page, showing all webhook attempts for the group.
Send Test Webhook: Sends mock data to your endpoint for testing. Useful for initial setup or debugging a broken webhook.
Delete: Permanently deletes the webhook group, including associated attempt logs and cancelling any Queued or Pending attempts. Note: Queued events scheduled close to deletion time may still be sent.
A webhook attempt represents an instance of BlockMark Registry sending a webhook to your endpoint. The Attempts table lists all attempts for a webhook group, categorised by status:
Pending: Created but not yet scheduled.
Queued: Created and scheduled for delivery.
In Progress: Currently being sent.
Sent: Delivered (successfully or unsuccessfully).
Cancelled: Cancelled by the user, or cancelled automatically when the webhook was deactivated.
Failed attempts are retried with an exponential backoff, up to 12 attempts, after which the webhook is marked as broken and retries stop until you fix it.
Clicking an attempt in the table opens a detailed view, showing the chain of attempts and information such as:
Data sent in the webhook.
Response body and status.
Other relevant metadata.
Monitor Attempts: Regularly check the Attempts page to ensure webhooks are delivered successfully.
Test Endpoints: Use the Send Test Webhook feature to validate your endpoint before going live.
Pause rather than delete: If your endpoint is going down for maintenance, pause the group. Events are retained and delivered when you resume, whereas deactivating discards them.
Backup Logs: Save critical attempt logs before deleting a webhook group, as deletion is irreversible.