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. The following webhooks are currently available:
| Webhook Name | Description |
|---|---|
| issued_certificate.created | Triggered when a certificate is issued. Requires selecting at least one certification scheme. The webhook only triggers for certificates issued under your selected scheme(s). |
| issued_certificate.updated | Triggered when a certificate is updated. Requires selecting at least one certification scheme. The webhook only triggers for updates to certificates in your selected scheme(s) and only for changes to the following fields: - name_on_certificate - has_name_mismatch - is_issued_to_thing - start_time - finish_time - status - hidden - is_test - is_archived - is_adopted - bespoke_id - is_to_guardian - is_self_certified - custom_fields - custom_notes |
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).
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 any related objects (e.g., certification schemes) to filter events.
Webhook groups are managed in the Webhooks section of the Organisation Settings page. Each group has a menu with the following actions:
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.
Edit: Allows modification of the group’s settings, such as changing the endpoint.
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.
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.
Backup Logs: Save critical attempt logs before deleting a webhook group, as deletion is irreversible.