Appearance
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 failurePublish outbound event
POST /v1/outbound-eventsAuthentication: 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-eventsAuthentication: 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}/replayAuthentication: 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.