Events (Outbound)

About 566 wordsAbout 2 min

Outbound events let your application publish webhooks to your customers via GetHook. You submit a payload; GetHook fans it out to all matching destinations based on your routes, handles signing, retries, and delivery tracking.

Typical flow

Your App → POST /v1/outbound-events
                → GetHook persists event
                → Worker picks up
                → Delivers to all matching destinations
                → Retry on failure

Publish outbound event

POST /v1/outbound-events

Authentication: Bearer

Request body

Field	Type	Required	Description
`payload`	string	Yes	The webhook body (usually a JSON string)
`event_type`	string	No	Event type tag (e.g. `order.created`). Used for route matching.
`external_event_id`	string	No	Idempotency key. Duplicate IDs are rejected.

Response `201 Created`

{
  "data": {
    "id": "e9e8e7e6-e5f6-7890-abcd-ef1234567890",
    "status": "queued"
  }
}

Errors

Status	Error	Cause
`400`	`payload is required`	Missing or empty payload
`401`	Unauthorized	Invalid Bearer token

curl examples

# Publish a simple event
curl -s -X POST http://localhost:8080/v1/outbound-events \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "order.created",
    "payload": "{\"order_id\": \"ord_123\", \"amount\": 4900}"
  }' | jq .

# With idempotency key
curl -s -X POST http://localhost:8080/v1/outbound-events \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "subscription.cancelled",
    "external_event_id": "sub_cancel_abc123",
    "payload": "{\"subscription_id\": \"sub_abc123\", \"reason\": \"user_requested\"}"
  }' | jq .

List outbound events

GET /v1/outbound-events

Authentication: Bearer

Returns the 50 most recent outbound events for the account.

Response `200 OK`

{
  "data": [
    {
      "id": "e9e8e7e6-...",
      "account_id": "a1a2a3a4-...",
      "direction": "outbound",
      "event_type": "order.created",
      "external_event_id": null,
      "status": "delivered",
      "attempts_count": 1,
      "received_at": "2024-01-15T11:00:00Z",
      "created_at": "2024-01-15T11:00:00Z"
    }
  ]
}

curl example

curl -s http://localhost:8080/v1/outbound-events \
  -H "Authorization: Bearer $API_KEY" | jq .

Get outbound event

Returns a single outbound event with its full payload and delivery attempts.

GET /v1/outbound-events/{id}

Authentication: Bearer

Path parameters

Parameter	Type	Description
`id`	UUID	The outbound event ID

Response `200 OK`

{
  "data": {
    "event": {
      "id": "e9e8e7e6-...",
      "account_id": "a1a2a3a4-...",
      "direction": "outbound",
      "event_type": "order.created",
      "body": "{\"order_id\": \"ord_123\", \"amount\": 4900}",
      "payload_hash": "sha256:def456...",
      "status": "delivered",
      "attempts_count": 1,
      "created_by": "api",
      "received_at": "2024-01-15T11:00:00Z"
    },
    "attempts": [
      {
        "id": "at5at6at7-...",
        "event_id": "e9e8e7e6-...",
        "destination_id": "d1d2d3d4-...",
        "attempt_number": 1,
        "outcome": "success",
        "response_status": 200,
        "attempted_at": "2024-01-15T11:00:05Z",
        "duration_ms": 98
      }
    ]
  }
}

curl example

curl -s http://localhost:8080/v1/outbound-events/e9e8e7e6-... \
  -H "Authorization: Bearer $API_KEY" | jq .

Replay outbound event

Marks the original event as replayed and re-queues a new delivery with the same payload.

POST /v1/outbound-events/{id}/replay

Authentication: Bearer

Response `202 Accepted`

{
  "data": {
    "original_event_id": "e9e8e7e6-...",
    "replay_event_id": "f0f1f2f3-...",
    "status": "queued"
  }
}

curl example

curl -s -X POST http://localhost:8080/v1/outbound-events/e9e8e7e6-.../replay \
  -H "Authorization: Bearer $API_KEY" | jq .

Setting up outbound webhooks

A typical SaaS outbound webhook setup:

# 1. Create a destination per customer
CUSTOMER_DEST=$(curl -s -X POST http://localhost:8080/v1/destinations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Acme Corp",
    "url": "https://acme.example.com/webhooks",
    "signing_secret": "acme-shared-secret-known-to-acme"
  }' | jq -r '.data.id')

# 2. Create a catch-all route to that destination
curl -s -X POST http://localhost:8080/v1/routes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"destination_id\": \"$CUSTOMER_DEST\"}" | jq .

# 3. Publish events when things happen in your system
curl -s -X POST http://localhost:8080/v1/outbound-events \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "invoice.paid",
    "payload": "{\"invoice_id\": \"inv_001\", \"amount\": 9900}"
  }' | jq .

Acme Corp receives a signed HTTP POST at https://acme.example.com/webhooks with the Webhook-Signature header they can verify using the shared secret.