Webhooks

GraphQL schema reference · API guide · SDKs

Webhook endpoints, deliveries, replays, and event types.

Types used by more than one domain are on Shared types.

Queries

Query.webhookDeliveriesConnection

List webhook deliveries newest first, optionally filtered. Only forward pagination is supported.

webhookDeliveriesConnection(
  endpointId: ID
  statuses: [WebhookDeliveryStatus!]
  eventType: String
  eventId: ID
  createdAfter: Time
  createdBefore: Time
  page: ConnectionInput
): WebhookDeliveriesConnection!

Returns: WebhookDeliveriesConnection! (WebhookDeliveriesConnection)

Arguments

endpointId: ID — Only deliveries to this endpoint.
statuses: [WebhookDeliveryStatus!] (WebhookDeliveryStatus) — Only deliveries in these statuses.
eventType: String — Only deliveries of this event type, e.g. “stream.live”.
eventId: ID — Only deliveries of this event.
createdAfter: Time (Time) — Only deliveries created at or after this time.
createdBefore: Time (Time) — Only deliveries created before this time.
page: ConnectionInput (ConnectionInput)

SDK

Operation	TypeScript	Go	Python
GetWebhookDeliveriesConnection	`GetWebhookDeliveriesConnectionDocument`	`GetWebhookDeliveriesConnection`	`get_webhook_deliveries_connection`

Query.webhookDelivery

Get one webhook delivery with every HTTP attempt.

webhookDelivery(
  id: ID!
): WebhookDelivery

Returns: WebhookDelivery (WebhookDelivery)

Arguments

id: ID!

SDK

Operation	TypeScript	Go	Python
GetWebhookDelivery	`GetWebhookDeliveryDocument`	`GetWebhookDelivery`	`get_webhook_delivery`

Query.webhookEndpoint

Get one of the tenant’s webhook endpoints.

webhookEndpoint(
  id: ID!
): WebhookEndpoint

Returns: WebhookEndpoint (WebhookEndpoint)

Arguments

id: ID!

SDK

Operation	TypeScript	Go	Python
GetWebhookEndpoint	`GetWebhookEndpointDocument`	`GetWebhookEndpoint`	`get_webhook_endpoint`

Query.webhookEndpointsConnection

List the tenant’s webhook endpoints, oldest first. A tenant has at most 10, so one page holds them all.

webhookEndpointsConnection(
  page: ConnectionInput
): WebhookEndpointsConnection!

Returns: WebhookEndpointsConnection! (WebhookEndpointsConnection)

Arguments

page: ConnectionInput (ConnectionInput)

SDK

Operation	TypeScript	Go	Python
GetWebhookEndpointsConnection	`GetWebhookEndpointsConnectionDocument`	`GetWebhookEndpointsConnection`	`get_webhook_endpoints_connection`

Query.webhookEventTypes

The public event types an endpoint can subscribe to, as used in eventTypes. ”*” subscribes to every type.

webhookEventTypes: [String!]!

Returns: [String!]!

SDK

Operation	TypeScript	Go	Python
GetWebhookEventTypes	`GetWebhookEventTypesDocument`	`GetWebhookEventTypes`	`get_webhook_event_types`

Mutations

Mutation.createWebhookEndpoint

Create an outbound webhook endpoint. The response carries the signing secret once; it is never returned again. A tenant can have at most 10 endpoints.

createWebhookEndpoint(
  input: CreateWebhookEndpointInput!
): CreateWebhookEndpointResult!

Returns: CreateWebhookEndpointResult! (CreateWebhookEndpointResult)

Arguments

input: CreateWebhookEndpointInput! (CreateWebhookEndpointInput)

SDK

Operation	TypeScript	Go	Python
CreateWebhookEndpoint	`CreateWebhookEndpointDocument`	`CreateWebhookEndpoint`	`create_webhook_endpoint`

Mutation.deleteWebhookEndpoint

Delete an endpoint with its signing secrets and delivery log.

deleteWebhookEndpoint(
  id: ID!
): DeleteWebhookEndpointResult!

Returns: DeleteWebhookEndpointResult! (DeleteWebhookEndpointResult)

Arguments

id: ID! — The endpoint ID.

SDK

Operation	TypeScript	Go	Python
DeleteWebhookEndpoint	`DeleteWebhookEndpointDocument`	`DeleteWebhookEndpoint`	`delete_webhook_endpoint`

Mutation.disableWebhookEndpoint

Disable an endpoint. Its pending deliveries are skipped.

disableWebhookEndpoint(
  id: ID!
): WebhookEndpointResult!

Returns: WebhookEndpointResult! (WebhookEndpointResult)

Arguments

id: ID! — The endpoint ID.

SDK

Operation	TypeScript	Go	Python
DisableWebhookEndpoint	`DisableWebhookEndpointDocument`	`DisableWebhookEndpoint`	`disable_webhook_endpoint`

Mutation.enableWebhookEndpoint

Enable a disabled endpoint. Deliveries skipped while it was disabled are not sent again; replay them with replayWebhookDeliveries.

enableWebhookEndpoint(
  id: ID!
): WebhookEndpointResult!

Returns: WebhookEndpointResult! (WebhookEndpointResult)

Arguments

id: ID! — The endpoint ID.

SDK

Operation	TypeScript	Go	Python
EnableWebhookEndpoint	`EnableWebhookEndpointDocument`	`EnableWebhookEndpoint`	`enable_webhook_endpoint`

Mutation.replayWebhookDeliveries

Send again the failed and skipped deliveries of one endpoint created in [createdAfter, createdBefore), oldest first, at most 1000 per call. Call again while hasMore is true.

replayWebhookDeliveries(
  endpointId: ID!
  createdAfter: Time!
  createdBefore: Time!
): ReplayWebhookDeliveriesResult!

Returns: ReplayWebhookDeliveriesResult! (ReplayWebhookDeliveriesResult)

Arguments

endpointId: ID!
createdAfter: Time! (Time)
createdBefore: Time! (Time)

SDK

Operation	TypeScript	Go	Python
ReplayWebhookDeliveries	`ReplayWebhookDeliveriesDocument`	`ReplayWebhookDeliveries`	`replay_webhook_deliveries`

Mutation.replayWebhookDelivery

Send a finished delivery again under the same ID, so the receiver sees the same webhook-id. The endpoint must be enabled.

replayWebhookDelivery(
  id: ID!
): ReplayWebhookDeliveryResult!

Returns: ReplayWebhookDeliveryResult! (ReplayWebhookDeliveryResult)

Arguments

id: ID! — The delivery ID.

SDK

Operation	TypeScript	Go	Python
ReplayWebhookDelivery	`ReplayWebhookDeliveryDocument`	`ReplayWebhookDelivery`	`replay_webhook_delivery`

Mutation.rotateWebhookEndpointSecret

Replace an endpoint’s signing secret and return the new one once. The previous secret keeps signing alongside it for 24 hours, unless revokePrevious is true.

rotateWebhookEndpointSecret(
  id: ID!
  revokePrevious: Boolean = false
): RotateWebhookEndpointSecretResult!

Returns: RotateWebhookEndpointSecretResult! (RotateWebhookEndpointSecretResult)

Arguments

id: ID! — The endpoint ID.
revokePrevious: Boolean (default false) — Stop signing with the previous secret immediately.

SDK

Operation	TypeScript	Go	Python
RotateWebhookEndpointSecret	`RotateWebhookEndpointSecretDocument`	`RotateWebhookEndpointSecret`	`rotate_webhook_endpoint_secret`

Mutation.testWebhookEndpoint

Send a signed webhook.test event to the endpoint and wait for the result. At most one test per endpoint every 10 seconds.

testWebhookEndpoint(
  id: ID!
): TestWebhookEndpointResult!

Returns: TestWebhookEndpointResult! (TestWebhookEndpointResult)

Arguments

id: ID! — The endpoint ID.

SDK

Operation	TypeScript	Go	Python
TestWebhookEndpoint	`TestWebhookEndpointDocument`	`TestWebhookEndpoint`	`test_webhook_endpoint`

Mutation.updateWebhookEndpoint

Change an endpoint’s URL, description, or event types. Omitted fields keep their value.

updateWebhookEndpoint(
  id: ID!
  input: UpdateWebhookEndpointInput!
): UpdateWebhookEndpointResult!

Returns: UpdateWebhookEndpointResult! (UpdateWebhookEndpointResult)

Arguments

id: ID! — The endpoint ID.
input: UpdateWebhookEndpointInput! (UpdateWebhookEndpointInput)

SDK

Operation	TypeScript	Go	Python
UpdateWebhookEndpoint	`UpdateWebhookEndpointDocument`	`UpdateWebhookEndpoint`	`update_webhook_endpoint`

Types

CreateWebhookEndpointInput

input_object

url: String! — An https URL of a public host that resolves. A host that does not exist is a ValidationError with code INVALID_ARGUMENT; a DNS lookup that failed in a way that may clear is a ValidationError with code FAILED_PRECONDITION, and the request can be retried.
description: String
eventTypes: [String!]! — Public event types to receive; ”*” receives every type. See webhookEventTypes.
apiVersion: String — Public event package version; defaults to “v1”.

CreateWebhookEndpointResult

union

DeleteWebhookEndpointResult

union

Member: DeleteSuccess
Member: NotFoundError
Member: AuthError

ReplayWebhookDeliveriesResult

union

Member: WebhookReplayResult
Member: ValidationError
Member: NotFoundError
Member: AuthError

ReplayWebhookDeliveryResult

union

Member: WebhookDelivery
Member: ValidationError
Member: NotFoundError
Member: AuthError

RotateWebhookEndpointSecretResult

union

TestWebhookEndpointResult

union

Member: WebhookTestResult
Member: NotFoundError
Member: RateLimitError
Member: AuthError

UpdateWebhookEndpointInput

input_object

url: String — Checked like CreateWebhookEndpointInput.url.
description: String
eventTypes: [String!] — Replaces the subscribed event types when set.

UpdateWebhookEndpointResult

union

Member: WebhookEndpoint
Member: ValidationError
Member: NotFoundError
Member: AuthError

WebhookDeliveriesConnection

object

edges: [WebhookDeliveryEdge!]! (WebhookDeliveryEdge)
nodes: [WebhookDelivery!]! (WebhookDelivery)
pageInfo: PageInfo! (PageInfo)
totalCount: Int!

WebhookDelivery

object

One delivery of one event to one endpoint, or a test delivery.

id: ID! — Delivery ID. A replay keeps it.
endpointId: ID!
eventId: ID — The event ID, sent as webhook-id and as the body’s id. Null for test deliveries.
eventType: String!
kind: WebhookDeliveryKind! (WebhookDeliveryKind)
status: WebhookDeliveryStatus! (WebhookDeliveryStatus)
attempts: Int! — Attempts since the delivery was created or last replayed.
nextAttemptAt: Time (Time) — When the next attempt is due; null unless pending.
lastStatusCode: Int! — HTTP status of the last attempt; 0 when no response arrived.
lastErrorClass: String! — Failure class of the last attempt: http_status, redirect, timeout, connection, tls, dns, or blocked_destination; internal when FrameWorks could not sign or render the delivery; empty after a success. A blocked_destination failure (the destination policy refuses the address the host resolves to) fails the delivery without a retry.
deliveredAt: Time (Time)
replayCount: Int!
lastReplayedAt: Time (Time)
createdAt: Time! (Time)
updatedAt: Time! (Time)
attemptHistory: [WebhookDeliveryAttempt!]! (WebhookDeliveryAttempt) — Every HTTP attempt, oldest first, including attempts before the last replay.

WebhookDeliveryAttempt

object

One HTTP attempt of a delivery.

id: ID!
attemptNumber: Int!
statusCode: Int! — HTTP status; 0 when no response arrived.
errorClass: String!
latencyMs: Int!
responseExcerpt: String! — At most 1 KiB of the response body. For a blocked_destination attempt, which gets no response, the destination policy’s reason.
attemptedAt: Time! (Time)

WebhookDeliveryEdge

object

cursor: String!
node: WebhookDelivery! (WebhookDelivery)

WebhookDeliveryKind

enum

EVENT
TEST

WebhookDeliveryStatus

enum

PENDING — Waiting for the first attempt or a retry.
SUCCEEDED
FAILED — Every attempt of the retry schedule (about 3 days) failed, or a test delivery failed.
SKIPPED — The endpoint was disabled before the delivery succeeded.

WebhookEndpoint

object

An outbound webhook endpoint. FrameWorks POSTs the tenant’s public events of the subscribed types to its URL, signed with the Standard Webhooks scheme (webhook-id, webhook-timestamp, webhook-signature headers).

id: ID! — Endpoint ID.
url: String! — The https URL deliveries are sent to.
description: String! — Free-text description.
eventTypes: [String!]! — Public event types the endpoint receives; ”*” receives every type.
apiVersion: String! — Public event package version the payloads are rendered with, e.g. “v1”.
status: WebhookEndpointStatus! (WebhookEndpointStatus)
disabledReason: WebhookEndpointDisabledReason (WebhookEndpointDisabledReason) — Why the endpoint is disabled; null while enabled.
disabledAt: Time (Time) — When the endpoint was disabled; null while enabled.
consecutiveFailures: Int! — Failed attempts since the last successful delivery.
failingSince: Time (Time) — First failed attempt since the last successful delivery.
lastSuccessAt: Time (Time)
lastFailureAt: Time (Time)
previousSecretExpiresAt: Time (Time) — Until when the previous signing secret still signs deliveries; null when there is none.
createdAt: Time! (Time)
updatedAt: Time! (Time)

WebhookEndpointDisabledReason

enum

USER — Disabled through the API or dashboard.
FAILING — Disabled automatically after at least 20 consecutive failed attempts over at least 5 days without a success.

WebhookEndpointEdge

object

cursor: String!
node: WebhookEndpoint! (WebhookEndpoint)

WebhookEndpointResult

union

Member: WebhookEndpoint
Member: NotFoundError
Member: AuthError

WebhookEndpointSecret

object

An endpoint with its signing secret, returned only when the secret is created or rotated.

endpoint: WebhookEndpoint! (WebhookEndpoint)
secret: String! — The signing secret, “whsec_” followed by base64. Store it now; it is never shown again.

WebhookEndpointStatus

enum

ENABLED
DISABLED

WebhookEndpointsConnection

object

edges: [WebhookEndpointEdge!]! (WebhookEndpointEdge)
nodes: [WebhookEndpoint!]! (WebhookEndpoint)
pageInfo: PageInfo! (PageInfo)
totalCount: Int!

WebhookReplayResult

object

The result of a range replay.

replayedCount: Int!
hasMore: Boolean! — More failed or skipped deliveries remain in the range.

WebhookTestResult

object

The result of a test delivery.

delivery: WebhookDelivery! (WebhookDelivery)
attempt: WebhookDeliveryAttempt! (WebhookDeliveryAttempt)