Event subscriptions

Manage subscriptions through this schema's GraphQL endpoint. Subscriptions and stored queries inherit its warehouse scope; they do not receive an warehouseId variable.

https://api.pack.cloud/v1/warehouses/{warehouseId}/graphql

The Organization and Warehouse APIs use the same management operation names. Their event topics, server variables, and projection schema differ. Topic, action, and trigger values are case-sensitive.

Create requires a unique key, a supported topic, at least one action, and an HTTPS uri. Actions that include update also require at least one trigger. Delivery is enabled by default when enabled is omitted. The key cannot be changed later.

Destinations must use HTTPS. PackCloud rejects URLs containing credentials or fragments, as well as private or otherwise unsafe destinations.

mutation CreateSubscription($input: EventSubscriptionCreateInput!) {
  eventSubscriptionCreate(input: $input) {
    eventSubscription {
      id
      key
      topic
      actions
      triggers
      uri
      enabled
      status
    }
    secret
  }
}

{
  "input": {
    "key": "fulfillment-updates",
    "topic": "Fulfillment",
    "actions": ["create", "update"],
    "triggers": ["fulfillment.status", "fulfillment.lines.quantity"],
    "uri": "https://events.example.com/packcloud/fulfillments",
    "query": "query FulfillmentEvent($fulfillmentId: ID!) { fulfillment(id: $fulfillmentId) { id reference status } }",
    "queryFilter": "fulfillment.reference:*",
    "enabled": true
  }
}

PackCloud generates the signing secret. It is returned only by create and rotation and cannot be queried later. Store it immediately; rotate it if it is lost.

The eventSubscriptionCreate reference lists every input field and the full response.

Triggers apply only to the update action: a subscription whose actions include update requires at least one trigger, and a create-only subscription may not have any. An update is delivered when at least one changed trigger matches your list. Create events are never filtered by triggers.

Relation-only paths such as fulfillment.lines select membership changes. More specific paths such as fulfillment.lines.quantity select changes to that field.

Every prefix with deeper triggers also has a wildcard form, such as fulfillment.*, fulfillment.lines.* and fulfillment.allocations.*. A wildcard selects every change beneath that prefix, and on a relation it also covers that relation gaining or losing a record, so fulfillment.lines.* covers a line being added or removed as well as any of a line's fields changing. Use fulfillment.* to follow every update on the topic, and a wildcard keeps selecting fields that are added to the catalog later. A relation without deeper triggers, such as fulfillment.events, has no wildcard form.

Paths ending in .events select new history entries on the resource.

A delivery reports the concrete paths in fields_changed, grouped by what happened to them. A record added to a relation lands in added, a record removed from one lands in removed, and a changed field value lands in updated. All three lists are always present and any of them can be empty. These paths identify the changed records and fields more precisely than the trigger catalog.

{
  "added": ["fulfillment[id: '<fulfillment-id>'].lines[id: '<added-line-id>']"],
  "updated": [
    "fulfillment[id: '<fulfillment-id>'].status",
    "fulfillment[id: '<fulfillment-id>'].lines[id: '<line-id>'].quantity"
  ],
  "removed": ["fulfillment[id: '<fulfillment-id>'].lines[id: '<removed-line-id>']"]
}

List subscriptions with cursor pagination, or retrieve one by ID.

query GetAndListSubscriptions($subscriptionId: ID!) {
  eventSubscription(id: $subscriptionId) {
    id
    key
    topic
    actions
    triggers
    uri
    enabled
    status
    pauseReason
    pausedAt
  }
  eventSubscriptions(first: 20) {
    edges { node { id key topic enabled status } }
    pageInfo { hasNextPage endCursor }
  }
}

{ "subscriptionId": "<event-subscription-id>" }

Update only the fields that should change. A valid update that corrects a structural problem makes the subscription active again while preserving its key and secret.

mutation UpdateSubscription($subscriptionId: ID!, $input: EventSubscriptionUpdateInput!) {
  eventSubscriptionUpdate(id: $subscriptionId, input: $input) {
    eventSubscription { id key uri enabled status pauseReason }
    userErrors { field message }
  }
}

{
  "subscriptionId": "<event-subscription-id>",
  "input": {
    "uri": "https://events.example.com/packcloud/current",
    "enabled": true
  }
}

Always request userErrors from update and deactivate mutations.

Rotation replaces only the secret. Store the replacement before discarding the old value.

mutation RotateSubscriptionSecret($subscriptionId: ID!) {
  eventSubscriptionRotateSecret(id: $subscriptionId) {
    eventSubscription { id key status }
    secret
  }
}

Deactivation disables and pauses the subscription while retaining its delivery history.

mutation DeactivateSubscription($subscriptionId: ID!) {
  eventSubscriptionDeactivate(id: $subscriptionId) {
    eventSubscription { id key enabled status pauseReason pausedAt }
    userErrors { field message }
  }
}

{ "subscriptionId": "<event-subscription-id>" }

The optional query adds its result as data in the delivery. Without a stored query, the envelope omits data.

• Provide exactly one named, read-only query operation.
• Mutations, subscriptions, and introspection are rejected.
• Use only the server variable listed for the selected topic.
• The query runs without a user identity and uses the endpoint's scope.
• Every connection must include exactly one literal first or last integer from 1 through 250. Omitting both or using a pagination variable is unsupported.

PackCloud supplies the declared resource variable from the event.

An optional queryFilter uses the same Shopify-style grammar as PackCloud search queries. It requires a stored query, and every filter field must be a scalar response path selected by that query. Aliases become part of the response path.

fulfillment.reference:*
fulfillment.status:shipped AND fulfillment.reference:"FUL-1001"
(fulfillment.status:shipped OR fulfillment.status:canceled) AND fulfillment.reference:FUL*
fulfillment.reference:>=FUL-1000
-fulfillment.reference:*

• Use field:value for equality and field:>value, :>=, :<, or :<= for ordering.
• Use AND, OR, NOT, a leading minus sign, parentheses, quoted values, and a trailing * for prefix matching. A standalone *tests whether a scalar is present; negate that term to test for an absent or null value.
• AND binds more tightly than OR.
• For list paths, a term matches when any selected list member matches.

A non-match is filtered before transport, so no request is sent for that subscription and event.

PackCloud sends an HTTPS POST with an application/json body.

{
  "event_id": "<event-id>",
  "delivery_id": "<delivery-id>",
  "topic": "Fulfillment",
  "action": "update",
  "subscription_key": "fulfillment-updates",
  "occurred_at": "<ISO-8601 timestamp>",
  "fields_changed": {
    "added": [],
    "updated": ["fulfillment[id: '<fulfillment-id>'].status"],
    "removed": []
  },
  "query_variables": { "fulfillmentId": "<fulfillment-id>" },
  "data": {
    "fulfillment": {
      "id": "<fulfillment-id>",
      "reference": "<fulfillment-reference>",
      "status": "<fulfillment-status>"
    }
  }
}

fields_changed always carries added, updated and removed. On a create delivery, added holds the path of the new resource and the other two lists are empty. data appears only when a stored query is configured and can be null.

Verify the signature against the raw request body and compare it in constant time.

$expected = base64_encode(hash_hmac('sha256', $rawBody, $secret, true));
$valid = hash_equals($expected, $receivedSignature);

Redirects are not followed. Deduplicate with delivery_id because transport retries are expected. There is no manual replay or payload recomputation.

After repeated terminal failures, PackCloud temporarily stops sending while continuing to queue matching deliveries. It tests the oldest pending delivery periodically and resumes oldest-first delivery after a successful response. Projection errors do not affect this recovery behavior.

Delivery history is read-only, newest first, and remains available through the subscription until its 30-day retention expires. Attempts are ordered from oldest to newest.

query DeliveryHistory($subscriptionId: ID!) {
  eventSubscription(id: $subscriptionId) {
    deliveries(first: 20) {
      edges {
        node {
          id
          eventId
          destination
          status
          attemptCount
          nextAttemptAt
          completedAt
          lastErrorCode
          lastError
          expiresAt
          createdAt
          attempts {
            attemptNumber
            outcome
            startedAt
            completedAt
            httpStatus
            errorCode
            error
          }
        }
      }
      pageInfo { hasNextPage endCursor }
    }
  }
}

Use status, nextAttemptAt, and the error fields to troubleshoot a delivery. The EventDelivery type reference reference lists all statuses and fields.

A structural failure means the stored document or its shape is no longer valid for the current schema. PackCloud records the failed delivery and pauses the subscription because another record cannot fix it. Correct the query or filter with a valid update to reactivate delivery.

A record-specific resolver, data, or payload-size failure affects only that delivery. It does not pause the subscription.