Skip to documentation

Guide · Webhooks

Available

Test the entire webhook lifecycle

A webhook event definition is a reusable template. A delivery is an observable attempt with rendered body, headers, signature, target, status, latency, retry lineage, and history.

In this guide

  • Create provider-shaped event templates
  • Preview without sending
  • Forward signed payloads to localhost
  • Trigger from a REST response and inspect delivery history

Prerequisites

  • A webhook DotMock workspace
  • The workspace ID in $API_ID
  • A reachable listener URL only when testing live delivery
On this page
  1. Create an event definition
  2. Render before delivery
  3. Connect a local listener
  4. Trigger and inspect a delivery
  5. Fire an event after a REST response
  6. Exercise retries and idempotency

Create an event definition

Create a webhook workspace, then add an enabled event with a stable key. Model the provider's content type, headers, body envelope, and signing convention rather than inventing a generic payload.

payment_intent.succeeded
{
  "id": "{{uuid}}",
  "type": "payment_intent.succeeded",
  "created": "{{now \"unix\"}}",
  "data": { "object": "{{paymentIntent}}" }
}

Render before delivery

A dashboard preview, MCP render, or CLI dry-run resolves the event with supplied data but sends nothing. It does not persist state, proxy, execute callouts, or create an external delivery.

bash
dotmock webhook trigger --api "$WEBHOOK_API_ID" --event payment_intent.succeeded --from payment.json --dry-run

Connect a local listener

Run the listener while developing. DotMock queues events for that live listener and forwards the rendered, signed request to your local callback. Use a fake local signing secret; never copy a provider production secret into a mock definition.

bash
dotmock webhook listen \
  --api "$WEBHOOK_API_ID" \
  --forward-to http://localhost:3000/webhooks/provider

Trigger and inspect a delivery

Trigger a real delivery only after the preview is correct. The result is stored durably with source=cli or source=ui, target, status, request snapshot, attempts, and timestamps.

bash
dotmock --json webhook trigger --api "$WEBHOOK_API_ID" --event payment_intent.succeeded --from payment.json
dotmock --json webhook inspect --api "$WEBHOOK_API_ID" --limit 20

Fire an event after a REST response

Response Hooks connect a REST operation to an enabled event on a webhook API in the same team. Matching and rendering complete first; the hook runs afterward and cannot change or delay the REST response when delivery fails.

bash
dotmock configure endpoint \
  --api "$REST_API_ID" \
  --method POST \
  --path /orders \
  --response-hook "$WEBHOOK_API_ID:order.created"

Exercise retries and idempotency

Make the local receiver return a deterministic 500, delay beyond its timeout, and then succeed. Verify signature handling, idempotency keys, duplicate delivery behavior, retry backoff, and the application's user-visible or operational result.

  • Inspect status code and latency for every attempt
  • Keep retryOf lineage when retrying a delivery
  • Assert duplicate events do not duplicate business effects
  • Use delivery history as evidence, not a configured success message