Advanced Topics

Webhook Management

This section provides a guide to managing Webhook endpoints and handling Webhook attempts within your Blocklet applications, enabling you to automate workflows and react to events on Blocklet Server. For details on directly interacting with the Blocklet Server API via GraphQL, refer to the GraphQL Client section.
Webhook Endpoints#Webhook endpoints are URLs where Blocklet Server sends event notifications. You can configure these endpoints to receive real-time updates about various activities happening on your Blocklet. Each endpoint can be configured with specific events it should listen for.
Here's a high-level overview of the webhook process:
"Your Blocklet Application""Blocklet Server""Your Blocklet Application""Blocklet Server"alt[Event Occurs on Blocklet Server][Webhook Delivery Fails]Create Webhook Endpoint (createWebhookEndpoint)Detect Event (e.g., user.created)Send Webhook Event (HTTP POST to endpoint URL)Acknowledge (HTTP 2xx)Send Webhook Event (HTTP POST)Error/TimeoutLog Failed Attempt (getWebhookAttempts)Retry Webhook Attempt (retryWebhookAttempt)

Create a Webhook Endpoint#Use the createWebhookEndpoint method to register a new Webhook endpoint with Blocklet Server. This allows your application to receive automated notifications for specified events.
Parameters
Name
Type
Description
teamDid
string
The DID of the team or Blocklet managing the webhook.
input
ABTNodeClient.RequestCreateWebhookEndpointInput
An object containing the details for the new webhook endpoint.
ABTNodeClient.WebhookEndpointStateInput Fields
Name
Type
Description
id
string
Optional. A unique identifier for the webhook endpoint. If not provided, one will be generated.
apiVersion
string
The API version to use for the webhook events (e.g., "1.0").
url
string
The URL where webhook events will be sent.
description
string
Optional. An optional description for the webhook endpoint.
enabledEvents
ABTNodeClient.EnableEventInput[]
An array of event types and sources to enable for this endpoint.
metadata
Record<string, any>
Optional. Custom metadata associated with the endpoint.
status
string
Optional. The status of the endpoint (e.g., "enabled", "disabled").
createdAt
number
Optional. Timestamp of creation.
updatedAt
number
Optional. Timestamp of last update.
ABTNodeClient.EnableEventInput Fields
Name
Type
Description
type
string
The type of event to enable (e.g., "user.created", "blocklet.started").
source
string
The source of the event (e.g., a Blocklet DID, "system").
Returns
Name
Type
Description
data
ABTNodeClient.WebhookEndpointState
The newly created webhook endpoint object.
Example
import ABTNodeClient from '@abtnode/client';

async function createWebhookEndpoint(teamDid, webhookUrl) {
  const client = new ABTNodeClient('http://localhost:8080'); // Replace with your Blocklet Server endpoint
  try {
    const response = await client.createWebhookEndpoint({
      teamDid,
      input: {
        apiVersion: '1.0',
        url: webhookUrl,
        description: 'Webhook for user creation and update events',
        enabledEvents: [
          { type: 'user.created', source: teamDid },
          { type: 'user.updated', source: teamDid },
        ],
      },
    });
    console.log('Webhook endpoint created successfully:', response.data.id);
    return response.data;
  } catch (error) {
    console.error('Error creating webhook endpoint:', error);
    throw error;
  }
}

// Usage example (replace with actual team DID and your webhook URL)
// createWebhookEndpoint('did:abt:zNKxVGF19f56e9qB4L9zF8Wz3t3V7t7P', 'https://your-app.com/webhooks');Example Response
{
  "code": 0,
  "data": {
    "id": "wh_someGeneratedId",
    "apiVersion": "1.0",
    "url": "https://your-app.com/webhooks",
    "description": "Webhook for user creation and update events",
    "enabledEvents": [
      {
        "type": "user.created",
        "source": "did:abt:zNKxVGF19f56e9qB4L9zF8Wz3t3V7t7P"
      },
      {
        "type": "user.updated",
        "source": "did:abt:zNKxVGF19f56e9qB4L9zF8Wz3t3V7t7P"
      }
    ],
    "metadata": {},
    "status": "enabled",
    "createdAt": 1678886400000,
    "updatedAt": 1678886400000
  }
}This example demonstrates how to create a new webhook endpoint that listens for user.created and user.updated events originating from a specific team DID.
Update a Webhook Endpoint#Use the updateWebhookEndpoint method to modify the details of an existing webhook endpoint, such as its URL, description, or enabled events.
Parameters
Name
Type
Description
teamDid
string
The DID of the team or Blocklet managing the webhook.
id
string
The unique identifier of the webhook endpoint to update.
data
PartialDeep<ABTNodeClient.WebhookEndpointStateInput>
An object containing the fields to update for the webhook endpoint.
Returns
Name
Type
Description
data
ABTNodeClient.WebhookEndpointState
The updated webhook endpoint object.
Example
import ABTNodeClient from '@abtnode/client';

async function updateWebhookEndpoint(teamDid, endpointId, newDescription) {
  const client = new ABTNodeClient('http://localhost:8080'); // Replace with your Blocklet Server endpoint
  try {
    const response = await client.updateWebhookEndpoint({
      teamDid,
      id: endpointId,
      data: {
        description: newDescription,
      },
    });
    console.log('Webhook endpoint updated successfully:', response.data.id);
    return response.data;
  } catch (error) {
    console.error('Error updating webhook endpoint:', error);
    throw error;
  }
}

// Usage example (replace with actual team DID, endpoint ID, and new description)
// updateWebhookEndpoint('did:abt:zNKxVGF19f56e9qB4L9zF8Wz3t3V7t7P', 'wh_someGeneratedId', 'Updated description for user events');Example Response
{
  "code": 0,
  "data": {
    "id": "wh_someGeneratedId",
    "apiVersion": "1.0",
    "url": "https://your-app.com/webhooks",
    "description": "Updated description for user events",
    "enabledEvents": [
      {
        "type": "user.created",
        "source": "did:abt:zNKxVGF19f56e9qB4L9zF8Wz3t3V7t7P"
      },
      {
        "type": "user.updated",
        "source": "did:abt:zNKxVGF19f56e9qB4L9zF8Wz3t3V7t7P"
      }
    ],
    "metadata": {},
    "status": "enabled",
    "createdAt": 1678886400000,
    "updatedAt": 1678886400000
  }
}This example updates the description of an existing webhook endpoint identified by its ID.
Delete a Webhook Endpoint#Use the deleteWebhookEndpoint method to remove a webhook endpoint from Blocklet Server. This will stop sending event notifications to the specified URL.
Parameters
Name
Type
Description
teamDid
string
The DID of the team or Blocklet managing the webhook.
id
string
The unique identifier of the webhook endpoint to delete.
Returns
Name
Type
Description
data
ABTNodeClient.WebhookEndpointState
The deleted webhook endpoint object.
Example
import ABTNodeClient from '@abtnode/client';

async function deleteWebhookEndpoint(teamDid, endpointId) {
  const client = new ABTNodeClient('http://localhost:8080'); // Replace with your Blocklet Server endpoint
  try {
    const response = await client.deleteWebhookEndpoint({
      teamDid,
      id: endpointId,
    });
    console.log('Webhook endpoint deleted successfully:', response.data.id);
    return response.data;
  } catch (error) {
    console.error('Error deleting webhook endpoint:', error);
    throw error;
  }
}

// Usage example (replace with actual team DID and endpoint ID)
// deleteWebhookEndpoint('did:abt:zNKxVGF19f56e9qB4L9zF8Wz3t3V7t7P', 'wh_someGeneratedId');Example Response
{
  "code": 0,
  "data": {
    "id": "wh_someGeneratedId",
    "apiVersion": "1.0",
    "url": "https://your-app.com/webhooks",
    "description": "Webhook for user creation and update events",
    "enabledEvents": [],
    "metadata": {},
    "status": "deleted",
    "createdAt": 1678886400000,
    "updatedAt": 1678886400000
  }
}This example deletes a specified webhook endpoint, halting all future notifications to its URL.
Get a Webhook Endpoint#Use the getWebhookEndpoint method to retrieve detailed information about a single webhook endpoint by its ID.
Parameters
Name
Type
Description
teamDid
string
The DID of the team or Blocklet that owns the webhook endpoint.
id
string
The unique identifier of the webhook endpoint to retrieve.
Returns
Name
Type
Description
data
ABTNodeClient.WebhookEndpointWithUserInfo
The requested webhook endpoint object, including associated user information.
Example
import ABTNodeClient from '@abtnode/client';

async function getSingleWebhookEndpoint(teamDid, endpointId) {
  const client = new ABTNodeClient('http://localhost:8080'); // Replace with your Blocklet Server endpoint
  try {
    const response = await client.getWebhookEndpoint({
      teamDid,
      id: endpointId,
    });
    console.log(`Retrieved webhook endpoint ${response.data.id}:`, response.data.description);
    return response.data;
  } catch (error) {
    console.error('Error retrieving webhook endpoint:', error);
    throw error;
  }
}

// Usage example (replace with actual team DID and endpoint ID)
// getSingleWebhookEndpoint('did:abt:zNKxVGF19f56e9qB4L9zF8Wz3t3V7t7P', 'wh_someGeneratedId');Example Response
{
  "data": {
    "id": "wh_someGeneratedId",
    "apiVersion": "1.0",
    "url": "https://your-app.com/webhooks",
    "description": "Webhook for user creation and update events",
    "enabledEvents": [
      {
        "type": "user.created",
        "source": "did:abt:zNKxVGF19f56e9qB4L9zF8Wz3t3V7t7P"
      },
      {
        "type": "user.updated",
        "source": "did:abt:zNKxVGF19f56e9qB4L9zF8Wz3t3V7t7P"
      }
    ],
    "metadata": {},
    "status": "enabled",
    "createdAt": 1678886400000,
    "updatedAt": 1678886400000,
    "createUser": {
      "did": "did:abt:zNKxVGF19f56e9qB4L9zF8Wz3t3V7t7P",
      "pk": "0x...",
      "role": "owner",
      "avatar": "",
      "fullName": "Admin User",
      "email": "admin@example.com",
      "approved": true,
      "createdAt": 1678800000000,
      "updatedAt": 1678800000000,
      "locale": "en"
    },
    "updateUser": {
      "did": "did:abt:zNKxVGF19f56e9qB4L9zF8Wz3t3V7t7P",
      "pk": "0x...",
      "role": "owner",
      "avatar": "",
      "fullName": "Admin User",
      "email": "admin@example.com",
      "approved": true,
      "createdAt": 1678800000000,
      "updatedAt": 1678800000000,
      "locale": "en"
    }
  }
}This example retrieves the full details, including user information, for a specific webhook endpoint.
Get Webhook Endpoints#Use the getWebhookEndpoints method to retrieve a paginated list of all webhook endpoints configured for a given team DID.
Parameters
Name
Type
Description
teamDid
string
The DID of the team or Blocklet whose webhook endpoints are to be retrieved.
paging
ABTNodeClient.PagingInput
Optional. Pagination parameters.
ABTNodeClient.PagingInput Fields
Name
Type
Description
total
number
The total number of items available across all pages.
pageSize
number
The maximum number of items to return per page.
pageCount
number
The total number of pages available.
page
number
The current page number to retrieve (1-indexed).
Returns
Name
Type
Description
list
ABTNodeClient.WebhookEndpointWithUserInfo[]
An array of webhook endpoint objects, including associated user information.
paging
ABTNodeClient.Paging
Pagination metadata.
Example
import ABTNodeClient from '@abtnode/client';

async function getWebhookEndpoints(teamDid) {
  const client = new ABTNodeClient('http://localhost:8080'); // Replace with your Blocklet Server endpoint
  try {
    const response = await client.getWebhookEndpoints({
      teamDid,
      paging: { page: 1, pageSize: 10 },
    });
    console.log(`Found ${response.list.length} webhook endpoints:`, 
      response.list.map(endpoint => endpoint.id));
    return response.list;
  } catch (error) {
    console.error('Error getting webhook endpoints:', error);
    throw error;
  }
}

// Usage example (replace with actual team DID)
// getWebhookEndpoints('did:abt:zNKxVGF19f56e9qB4L9zF8Wz3t3V7t7P');Example Response
{
  "list": [
    {
      "id": "wh_someGeneratedId",
      "apiVersion": "1.0",
      "url": "https://your-app.com/webhooks",
      "description": "Webhook for user creation and update events",
      "enabledEvents": [
        {
          "type": "user.created",
          "source": "did:abt:zNKxVGF19f56e9qB4L9zF8Wz3t3V7t7P"
        },
        {
          "type": "user.updated",
          "source": "did:abt:zNKxVGF19f56e9qB4L9zF8Wz3t3V7t7P"
        }
      ],
      "metadata": {},
      "status": "enabled",
      "createdAt": 1678886400000,
      "updatedAt": 1678886400000,
      "createUser": {
        "did": "did:abt:zNKxVGF19f56e9qB4L9zF8Wz3t3V7t7P",
        "fullName": "Admin User"
      }
    }
  ],
  "paging": {
    "total": 1,
    "pageSize": 10,
    "pageCount": 1,
    "page": 1
  }
}This example retrieves a list of the first 10 webhook endpoints for a specified team, showing their IDs.
Webhook Attempts#Webhook attempts represent individual delivery attempts of an event notification to a configured webhook endpoint. You can inspect these attempts to troubleshoot delivery failures or monitor webhook activity.
Get Webhook Attempts#Use the getWebhookAttempts method to retrieve a paginated list of webhook delivery attempts. You can filter attempts by eventId or webhookId.
Parameters
Name
Type
Description
teamDid
string
The DID of the team or Blocklet managing the webhooks.
input
ABTNodeClient.RequestGetWebhookAttemptsInput['input']
An object specifying the eventId and/or webhookId to filter attempts.
paging
ABTNodeClient.PagingInput
Optional. Pagination parameters.
ABTNodeClient.RequestAttemptIdInput Fields
Name
Type
Description
eventId
string
Optional. The ID of the event for which to retrieve attempts.
webhookId
string
Optional. The ID of the webhook endpoint for which to retrieve attempts.
Returns
Name
Type
Description
list
ABTNodeClient.WebhookAttemptWithEndpointEventState[]
An array of webhook attempt objects, including associated endpoint and event information.
paging
ABTNodeClient.Paging
Pagination metadata.
ABTNodeClient.WebhookAttemptWithEndpointEventState Fields
Name
Type
Description
id
string
The unique identifier for this webhook attempt.
eventId
string
The ID of the event that triggered this attempt.
webhookId
string
The ID of the webhook endpoint this attempt was sent to.
status
string
The status of the attempt (e.g., "succeeded", "failed", "pending").
responseStatus
number
The HTTP status code returned by the endpoint (if any).
responseBody
Record<string, any>
The response body from the endpoint (if any).
retryCount
number
The number of retries for this attempt.
createdAt
number
Timestamp when the attempt was created.
updatedAt
number
Timestamp when the attempt was last updated.
endpoint
ABTNodeClient.WebhookEndpointState
Details of the webhook endpoint.
event
ABTNodeClient.WebhookEventState
Details of the event that triggered the webhook.
triggeredBy
string
The entity that triggered the webhook (e.g., "system", "user").
triggeredFrom
string
The source of the trigger (e.g., "automation", "manual").
Example
import ABTNodeClient from '@abtnode/client';

async function getWebhookAttempts(teamDid, webhookId) {
  const client = new ABTNodeClient('http://localhost:8080'); // Replace with your Blocklet Server endpoint
  try {
    const response = await client.getWebhookAttempts({
      teamDid,
      input: { webhookId },
      paging: { page: 1, pageSize: 10 },
    });
    console.log(`Found ${response.list.length} webhook attempts for webhook ${webhookId}:`);
    response.list.forEach(attempt => {
      console.log(`- Attempt ID: ${attempt.id}, Status: ${attempt.status}, Response Status: ${attempt.responseStatus}`);
    });
    return response.list;
  } catch (error) {
    console.error('Error getting webhook attempts:', error);
    throw error;
  }
}

// Usage example (replace with actual team DID and webhook ID)
// getWebhookAttempts('did:abt:zNKxVGF19f56e9qB4L9zF8Wz3t3V7t7P', 'wh_someGeneratedId');Example Response
{
  "list": [
    {
      "id": "att_someAttemptId",
      "eventId": "evt_someEventId",
      "webhookId": "wh_someGeneratedId",
      "status": "succeeded",
      "responseStatus": 200,
      "responseBody": {},
      "retryCount": 0,
      "createdAt": 1678886400000,
      "updatedAt": 1678886400000,
      "endpoint": {
        "id": "wh_someGeneratedId",
        "apiVersion": "1.0",
        "url": "https://your-app.com/webhooks",
        "description": "Webhook for user creation and update events",
        "enabledEvents": [],
        "metadata": {},
        "status": "enabled",
        "createdAt": 1678886400000,
        "updatedAt": 1678886400000
      },
      "event": {
        "id": "evt_someEventId",
        "type": "user.created",
        "apiVersion": "1.0",
        "data": {},
        "objectType": "User",
        "objectId": "user_someUserId",
        "request": {},
        "pendingWebhooks": 0,
        "metadata": {},
        "createdAt": 1678886300000,
        "updatedAt": 1678886300000,
        "source": "did:abt:zNKxVGF19f56e9qB4L9zF8Wz3t3V7t7P"
      },
      "triggeredBy": "system",
      "triggeredFrom": "automation"
    }
  ],
  "paging": {
    "total": 1,
    "pageSize": 10,
    "pageCount": 1,
    "page": 1
  }
}This example retrieves the first 10 webhook attempts for a specific webhook endpoint, displaying their status and response codes.
Retry a Webhook Attempt#Use the retryWebhookAttempt method to re-attempt the delivery of a failed webhook event. This can be useful for re-processing events after an issue with your endpoint has been resolved.
Parameters
Name
Type
Description
teamDid
string
The DID of the team or Blocklet managing the webhook.
input
ABTNodeClient.RequestAttemptInput
An object containing the eventId, webhookId, and attemptId of the attempt to retry.
ABTNodeClient.RequestAttemptInput Fields
Name
Type
Description
eventId
string
The ID of the event associated with the attempt.
webhookId
string
The ID of the webhook endpoint associated with the attempt.
attemptId
string
The ID of the specific attempt to retry.
teamDid
string
The DID of the team or Blocklet managing the webhook. (Note: This is duplicated in the top-level params and input object for this method.)
Returns
Name
Type
Description
data
ABTNodeClient.WebhookAttemptState
The retried webhook attempt object.
Example
import ABTNodeClient from '@abtnode/client';

async function retryWebhookAttempt(teamDid, eventId, webhookId, attemptId) {
  const client = new ABTNodeClient('http://localhost:8080'); // Replace with your Blocklet Server endpoint
  try {
    const response = await client.retryWebhookAttempt({
      teamDid,
      input: {
        eventId,
        webhookId,
        attemptId,
        teamDid, // teamDid is part of input as well
      },
    });
    console.log('Webhook attempt retried successfully:', response.data.id, 'New Status:', response.data.status);
    return response.data;
  } catch (error) {
    console.error('Error retrying webhook attempt:', error);
    throw error;
  }
}

// Usage example (replace with actual DIDs and IDs)
// retryWebhookAttempt(
//   'did:abt:zNKxVGF19f56e9qB4L9zF8Wz3t3V7t7P',
//   'evt_someEventId',
//   'wh_someGeneratedId',
//   'att_someFailedAttemptId'
// );Example Response
{
  "code": 0,
  "data": {
    "id": "att_someFailedAttemptId",
    "eventId": "evt_someEventId",
    "webhookId": "wh_someGeneratedId",
    "status": "pending",
    "responseStatus": 0,
    "responseBody": {},
    "retryCount": 1,
    "createdAt": 1678886400000,
    "updatedAt": 1678886500000,
    "triggeredBy": "user",
    "triggeredFrom": "manual"
  }
}This example demonstrates how to retry a specific webhook delivery attempt, which will trigger a new attempt to send the event.

This section provided a comprehensive overview of managing webhook endpoints and their delivery attempts using the Blocklet SDK. You are now equipped to configure event notifications and monitor their delivery within your Blocklet applications. Proceed to the API Reference for a full, automatically generated list of all available methods and types.

Name	Type	Description
`id`	`string`	Optional. A unique identifier for the webhook endpoint. If not provided, one will be generated.
`apiVersion`	`string`	The API version to use for the webhook events (e.g., "1.0").
`url`	`string`	The URL where webhook events will be sent.
`description`	`string`	Optional. An optional description for the webhook endpoint.
`enabledEvents`	`ABTNodeClient.EnableEventInput[]`	An array of event types and sources to enable for this endpoint.
`metadata`	`Record<string, any>`	Optional. Custom metadata associated with the endpoint.
`status`	`string`	Optional. The status of the endpoint (e.g., "enabled", "disabled").
`createdAt`	`number`	Optional. Timestamp of creation.
`updatedAt`	`number`	Optional. Timestamp of last update.

Name	Type	Description
`total`	`number`	The total number of items available across all pages.
`pageSize`	`number`	The maximum number of items to return per page.
`pageCount`	`number`	The total number of pages available.
`page`	`number`	The current page number to retrieve (1-indexed).

Name	Type	Description
`teamDid`	`string`	The DID of the team or Blocklet managing the webhooks.
`input`	`ABTNodeClient.RequestGetWebhookAttemptsInput['input']`	An object specifying the `eventId` and/or `webhookId` to filter attempts.
`paging`	`ABTNodeClient.PagingInput`	Optional. Pagination parameters.

Name	Type	Description
`id`	`string`	The unique identifier for this webhook attempt.
`eventId`	`string`	The ID of the event that triggered this attempt.
`webhookId`	`string`	The ID of the webhook endpoint this attempt was sent to.
`status`	`string`	The status of the attempt (e.g., "succeeded", "failed", "pending").
`responseStatus`	`number`	The HTTP status code returned by the endpoint (if any).
`responseBody`	`Record<string, any>`	The response body from the endpoint (if any).
`retryCount`	`number`	The number of retries for this attempt.
`createdAt`	`number`	Timestamp when the attempt was created.
`updatedAt`	`number`	Timestamp when the attempt was last updated.
`endpoint`	`ABTNodeClient.WebhookEndpointState`	Details of the webhook endpoint.
`event`	`ABTNodeClient.WebhookEventState`	Details of the event that triggered the webhook.
`triggeredBy`	`string`	The entity that triggered the webhook (e.g., "system", "user").
`triggeredFrom`	`string`	The source of the trigger (e.g., "automation", "manual").

Name	Type	Description
`teamDid`	`string`	The DID of the team or Blocklet managing the webhook.
`input`	`ABTNodeClient.RequestAttemptInput`	An object containing the `eventId`, `webhookId`, and `attemptId` of the attempt to retry.

Overview

Get Started

Core Services

Middleware Reference

Utilities

Advanced Topics

API Reference

Webhook Management

Webhook Endpoints#

Create a Webhook Endpoint#

Update a Webhook Endpoint#

Delete a Webhook Endpoint#

Get a Webhook Endpoint#

Get Webhook Endpoints#

Webhook Attempts#

Get Webhook Attempts#

Retry a Webhook Attempt#

GraphQL Client

API Reference

Name	Type	Description
`type`	`string`	The type of event to enable (e.g., "user.created", "blocklet.started").
`source`	`string`	The source of the event (e.g., a Blocklet DID, "system").

Name	Type	Description
`teamDid`	`string`	The DID of the team or Blocklet that owns the webhook endpoint.
`id`	`string`	The unique identifier of the webhook endpoint to retrieve.

Name	Type	Description
`teamDid`	`string`	The DID of the team or Blocklet whose webhook endpoints are to be retrieved.
`paging`	`ABTNodeClient.PagingInput`	Optional. Pagination parameters.

Name	Type	Description
`list`	`ABTNodeClient.WebhookEndpointWithUserInfo[]`	An array of webhook endpoint objects, including associated user information.
`paging`	`ABTNodeClient.Paging`	Pagination metadata.

Name	Type	Description
`eventId`	`string`	Optional. The ID of the event for which to retrieve attempts.
`webhookId`	`string`	Optional. The ID of the webhook endpoint for which to retrieve attempts.

Name	Type	Description
`list`	`ABTNodeClient.WebhookAttemptWithEndpointEventState[]`	An array of webhook attempt objects, including associated endpoint and event information.
`paging`	`ABTNodeClient.Paging`	Pagination metadata.

Name	Type	Description
`eventId`	`string`	The ID of the event associated with the attempt.
`webhookId`	`string`	The ID of the webhook endpoint associated with the attempt.
`attemptId`	`string`	The ID of the specific attempt to retry.
`teamDid`	`string`	The DID of the team or Blocklet managing the webhook. (Note: This is duplicated in the top-level `params` and `input` object for this method.)