WebHooks

What are Webhooks?#

Within the ArcBlock Blocklet ecosystem, Webhooks provide a powerful mechanism for your Blocklet to react to platform events.

Imagine constantly polling a Blocklet for new data or events, much like repeatedly refreshing your inbox. Webhooks offer a different approach: they act as smart notifications. When a specific event occurs, the Blocklet pushes event data to a pre-configured URL, similar to receiving instant push notifications for new emails. This method is both efficient and timely.

Webhooks offer extensive integration capabilities, enabling your Blocklet to connect seamlessly with other services for automated workflows.

• When the Discuss Kit Blocklet publishes new content, your Blocklet can immediately receive this update.
• When the Vote Blocklet completes voting, your Blocklet can receive real-time updates on vote creation.
• You can even define custom events, enabling your Blocklet to publish notifications.

When creating a webhook, simply specify a URL and subscribe to the events you wish to monitor on the designated Blocklet. The Blocklet Service will then send an HTTP request containing the relevant event data to your specified URL whenever those events are triggered. If your server is configured to listen for webhook requests at that URL, it can act immediately upon receiving them.

Registering an Event#

In a Blocklet, you don't typically register webhook events directly within blocklet.yml. Instead, blocklet.yml primarily defines the Blocklet's metadata, configuration, and capabilities. The Blocklet Service uses this information to discover events the Blocklet needs to listen for. See the Event Bus Service (Beta) documentation for details.

To enable your Blocklet to send events to a webhook, you need to:

• Understand and configure the Event Bus Service: This is a crucial step. Refer to https://www.arcblock.io/content/docs/blocklet-developer/en/event-bus-service to understand its functionality and configuration. Webhooks can only discover events that are correctly published to the event bus.
• Creating Webhooks in Blocklet Services:
• • Access your Blocklet Service dashboard.
  • Navigate to the Webhook configuration section.
  • Here, you will be able to discover the available events exposed by the Blocklet Service via the Event Bus (e.g., vote.published, discuss.published, or your custom events).
  • Select the events you want to capture.
  • Specify the URL to which the webhook will send data when these events are triggered.

Example Workflow#

The following simplified example demonstrates how to configure a webhook to send a Slack notification when a vote.published event occurs:

• Configure the Event Hub:
• • Ensure your voting Blocklet is configured correctly and publishes vote.published events to the Event Bus Service.
  • For setup instructions, please see https://www.arcblock.io/content/docs/blocklet-developer/en/event-bus-service.
• Creating a Webhook:
• • In the Blocklet Service webhook management interface, click "Create New Webhook".
  • In the event list, locate and select the event you want to capture, for example, vote.published.
  • In the "URL" field, enter your Slack Incoming Webhook URL (the channel-specific webhook address Slack provides) or any other webhook URL.

• Configuration complete. Real-time notifications are now active.
• • After creation, when a new vote is published in your voting Blocklet (that is, when the vote.published event is triggered), the Blocklet Service automatically sends an HTTP request to your configured Slack URL.
  • Slack will receive the data from this request and, based on your Slack Webhook configuration, display a notification in the designated channel.