Skip to main content

WebhookSubscription

A request to be notified about a topic at a destination. Notifications carry only the ids of the affected entities and a timestamp; fetch the current state through the API. Subscriptions belong to the API token that created them: a token only sees and manages its own.

Delivery itself runs outside the shop, which is why every field from active through lastErrorMessage is a mirror of what the delivery service reports and is refreshed whenever the shop talks to it. A quiet shop's mirror can be up to a minute behind. Deliveries only start once the destination has consented, so a freshly created subscription reads consentState: Pending until then.

type WebhookSubscription implements Node {
  id: ID!
  abandonedCount: Int
  active: Boolean!
  consecutiveAbandonedCount: Int
  consentState: WebhookConsentState!
  consentVerifiedAt: DateTime
  createdAt: DateTime!
  deliveredCount: Int
  destinationConfig: JSON!
  destinationType: String!
  disabledAt: DateTime
  disabledReason: WebhookSubscriptionDisabledReason
  lastDeliveredAt: DateTime
  lastErrorAt: DateTime
  lastErrorMessage: String
  lastErrorStatusCode: Int
  reactivationBlockedUntil: DateTime
  signingSecret: String
  topic: String!
}

Fields​

WebhookSubscription.id ● ID! non-null scalar​

Global identifier for this entity.

WebhookSubscription.abandonedCount ● Int scalar​

Notifications given up on after 72 hours of retries since the subscription was created.

WebhookSubscription.active ● Boolean! non-null scalar​

False once the subscription was disabled, which happens when deliveries kept failing or the destination answered 410 Gone. See disabledReason.

WebhookSubscription.consecutiveAbandonedCount ● Int scalar​

Notifications abandoned in a row. The subscription is disabled automatically when this reaches ten; a delivered notification resets it.

Whether the destination currently consents to receiving webhooks.

When the destination last consented.

WebhookSubscription.createdAt ● DateTime! non-null scalar​

When the subscription was created. Also the order the list is paginated in, newest first.

WebhookSubscription.deliveredCount ● Int scalar​

Notifications that reached the destination since the subscription was created.

WebhookSubscription.destinationConfig ● JSON! non-null scalar​

Destination configuration as normalized on creation. For http: { "url": "…" }.

WebhookSubscription.destinationType ● String! non-null scalar​

Technical name of the destination type, e.g. http. Determines the shape of destinationConfig.

WebhookSubscription.disabledAt ● DateTime scalar​

When the subscription was disabled. Null while it is active.

WebhookSubscription.disabledReason ● WebhookSubscriptionDisabledReason enum​

Why the subscription was disabled. Null while it is active.

WebhookSubscription.lastDeliveredAt ● DateTime scalar​

When a notification last reached the destination.

WebhookSubscription.lastErrorAt ● DateTime scalar​

When the last failed delivery attempt was made.

WebhookSubscription.lastErrorMessage ● String scalar​

What went wrong on the last failed attempt, as a short technical phrase.

WebhookSubscription.lastErrorStatusCode ● Int scalar​

HTTP status the destination answered on the last failed attempt. Null when the attempt failed before a response, e.g. on a connection timeout.

WebhookSubscription.reactivationBlockedUntil ● DateTime scalar​

Until when reactivateWebhookSubscription is refused after an automatic disable. Null when re-activation is possible right now.

WebhookSubscription.signingSecret ● String scalar​

Secret for verifying the X-Pickware-Signature header of deliveries (32 bytes, lowercase hex). Returned exactly once: only in the response of the createWebhookSubscription mutation that created this subscription. Every later read returns null; a lost secret means deleting the subscription and creating it again.

WebhookSubscription.topic ● String! non-null scalar​

Topic the subscription is for, e.g. order/completely-shipped.

Interfaces​

Node interface​

Any entity that can be loaded by its global id through the node(id: ID!) query.

Returned By​

createWebhookSubscription mutation ● reactivateWebhookSubscription mutation ● webhookSubscription query

Member Of​

WebhookSubscriptionEdge object