Webhooks User Guide

Documentation
1

Overview

Smoke Signal supports XRPC webhooks through a configurable webhook service that implements the events.smokesignal.automation.InvokeWebhook XRPC method. This experimental feature allows you to receive real-time notifications when specific events occur in your Smoke Signal instance.

:warning: Experimental Feature Notice
This webhook functionality is experimental and may change significantly or be disabled in future releases.

Configuration

Service Identifier Requirements

To configure webhooks, your service must:

  1. Support the events.smokesignal.automation.InvokeWebhook XRPC method
  2. Use the required service identifier: SmokeSignalAutomation

Service ID Format

The complete service ID follows this pattern:

{your-service-did}#SmokeSignalAutomation

Example:

did:web:smokesignal-hooks.example.com#SmokeSignalAutomation

This would configure webhooks to be sent to the did:web:smokesignal-hooks.example.com service.

Supported Events

Smoke Signal currently supports three webhook event types:

Event Type Description
test Test event for webhook verification
rsvp.created Triggered when a new RSVP is created
event.created Triggered when a new event is created

XRPC Method Specification

Method Name

events.smokesignal.automation.InvokeWebhook

Input Schema

The webhook payload is sent as JSON with the following structure:

{
  "event": "string",     // One of: "test", "rsvp.created", "event.created"
  "record": {},          // Object containing event-specific data
  "context": {}          // Object containing additional context information
}

Required Fields:

  • event - The event type (must be one of the supported values)
  • record - Event-specific data object
  • context - Additional context object

Output Schema

Your webhook endpoint should return a JSON response. The specific structure is flexible, but it must be valid JSON.

{}

Reference Implementation

A complete reference implementation is available at:
@smokesignal.events/xrpcs-emailer at main · tangled

This implementation demonstrates how to:

  • Set up an XRPC webhook service
  • Handle the different event types
  • Process webhook payloads
  • Return appropriate responses

Troubleshooting

Common Issues

  1. Service not receiving webhooks

    • Verify your service DID is correctly formatted
    • Ensure the #SmokeSignalAutomation fragment is included
    • Check that your XRPC method name matches exactly: events.smokesignal.automation.InvokeWebhook

  2. Invalid payload errors

    • Confirm your service accepts JSON input
    • Verify all required fields (event, record, context) are being processed
    • Check that the event value is one of the supported types

  3. Authentication issues

    • Ensure your DID is properly configured and accessible
    • Verify XRPC authentication is set up correctly

Testing Your Implementation

Use the test event type to verify your webhook service is working correctly. This event can be triggered manually to ensure your endpoint receives and processes webhooks properly.

Limitations

  • This is an experimental feature and may change without notice
  • Currently supports only three event types
  • Limited to XRPC-compatible services
  • Requires proper DID configuration