Dispatch data to a third-party webhook

What you'll build

A custom trigger and an Action that POSTs JSON to a third-party URL when the trigger fires. Use Webhook.site as a temporary endpoint so you can inspect the request body and confirm delivery.

1. Prerequisites

1. A unique URL from Webhook.site (copy Your unique URL, not the browser address bar)
2. The WEBHOOK_URL environment secret set to that URL

2. Create the trigger

Navigate to the Triggers section to create a new trigger. Configure it with the following settings:

• Name: Dispatch webhook
• Slug: dispatch-webhook

On the Schema tab, export an interface that describes the payload callers must send:

export interface DispatchWebhookPayload {
  event: string;
  resourceId: string;
}

See Triggers for more information on creating a trigger and defining a schema.

3. Create the action

Navigate to the Actions section to create a new action. Configure it with the following settings:

• Name: Post to webhook
• Trigger: Dispatch webhook
• Action Retries: 0
• Users: All Users

See Actions for more information on creating an action.

4. Update the workflow

Update the action's workflow to POST the trigger payload to your webhook URL. The destination comes from the WEBHOOK_URL environment variable:

const workflow: ActionWorkflow = async ({ payload, identity, env }) => {
  const data = payload as { event?: string; resourceId?: string };

  const response = await fetch(`${env.WEBHOOK_URL}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      event: data.event ?? "unknown",
      resourceId: data.resourceId ?? null,
      identity: identity?.identifier ?? null,
      userType: identity?.userType ?? null,
    }),
  });

  if (!response.ok) {
    return { status: "failure", result: { status: response.status } };
  }

  return { status: "success" };
};

export default workflow;

5. Fire the trigger

From a Surface or other workflow, call utils.triggers.fire with the trigger slug and a payload that matches the schema:

await utils.triggers.fire(
  "dispatch-webhook",
  { event: "resource.viewed", resourceId: resource.id ?? "" },
  identity,
);

See Call an action from a workflow for a complete Surface example.

Result

When the trigger fires, the action POSTs JSON to your Webhook.site URL. On the Webhook.site page for that URL, confirm a POST request arrived with event, resourceId, identity, and userType in the body.

In Observability, the action event shows success or failure based on the HTTP response status.

Additional resources

• Send a Slack message from an Action
• Call an action from a workflow
• Actions
• Triggers
• Action Workflows reference
• Managing environments
• Observability