WebhookDeliveryResp

A single webhook delivery — the event payload that was sent (or queued to be sent), the customer endpoint's response, and the retry history. Each delivery corresponds to ONE event firing against ONE webhook endpoint; a single event that fans out to N configs creates N deliveries.

  • attempts
    Type: array object[] · WebhookDeliveryAttempt[]

    All delivery attempts made for this event. Each entry records the response (status code, body, error) and how long the request took, plus an attemptNumber you can sort by. Length grows up to retryConfig.maxAttempts.

    One delivery attempt against the customer's webhook URL. Records the HTTP response (status code + body, truncated for storage) or the error if the request couldn't complete (DNS, connection reset, timeout). Always at least one attempt; subsequent attempts appear here as the retry policy fires.

    • attemptedAt
      Type: stringFormat: date-time

      When the attempt was made

    • attemptNumber
      Type: integer

      Attempt number (1-based)

    • duration
      Type: integer

      Request duration in milliseconds

    • errorMessage
      Type: string

      Reason the attempt failed when no HTTP response was received (e.g., ETIMEDOUT, ECONNREFUSED, getaddrinfo ENOTFOUND). Absent when the customer endpoint did respond — check responseStatus then.

    • responseBody
      Type: string

      Customer endpoint's response body, truncated. Absent when the request couldn't complete.

    • responseStatus
      Type: integer

      HTTP status code returned by the customer endpoint. Absent when the request couldn't complete (network error, timeout) — see errorMessage instead.

  • createdAt
    Type: stringFormat: date-time

    When the event fired and the delivery was queued. Treat this as the event's wall-clock time on the SignStack side — usually within a few hundred ms of the underlying workflow / step / envelope transition.

  • envelopeKey
    Type: string

    Envelope key that triggered this event, when applicable.

  • eventId
    Type: string Pattern: ^evt_[0-9a-z]{26}$

    Stable per-event identifier — included in the payload as eventId. Same across retries of the same delivery; consumers can use it to dedupe. Prefixed lowercase ULID, e.g. evt_01jv8m7qfj6xj9gkz7a4s2h8e.

  • eventType
    Type: stringenum

    The event type that triggered this delivery. See WebhookEventType for the full set.

    values
    • workflow.started
    • workflow.failed
    • workflow.completed
    • workflow.declined
    • workflow.voided
  • id
    Type: string Pattern: ^wd_[0-9a-z]{26}$

    Unique identifier for the delivery. Prefixed lowercase ULID, e.g. wd_01jv8m7qfj6xj9gkz7a4s2h8e.

  • nextRetryAt
    Type: stringFormat: date-time

    When the next retry will fire, when status: pending and at least one attempt has failed. Absent on success, failed, and on the first attempt before any failure.

  • participantEmail
    Type: string

    Email of the participant the event is about, when applicable.

  • payload
    Type: object

    The JSON envelope POSTed to your webhook endpoint when an event fires. Branch on apiVersion and eventType in your handler — never rely on field presence alone, since new event types add new shapes inside data over time.

    • apiVersion
      enum
      const:  
      1
      required

      Schema version of this payload. Today's value is "1". New versions will be added as the envelope or per-event data shapes change in backwards-incompatible ways; old payloads keep flowing under their original version. Always branch on this in your handler before reading data.

      values
      • 1
    • data
      Type: object
      required

      Event-specific payload. Shape depends on eventType:

      • workflow.* — carries workflowId. workflow.failed additionally carries errorMessage.
      • step.* — carries workflowId, stepKey, stepType. step.failed additionally carries errorMessage.
      • participant.* — carries workflowId, stepKey, participantEmail, participantId, envelopeKey.
      • envelope.* — carries workflowId, envelopeKey.

      Always check eventType (and apiVersion) before reading specific fields off data.

    • eventId
      Type: string Pattern: ^evt_[0-9a-z]{26}$
      required

      Stable per-event identifier — same value across retries of the same delivery. Use as your dedup key on the consumer side. Prefixed lowercase ULID, e.g. evt_01jv8m7qfj6xj9gkz7a4s2h8e.

    • eventType
      Type: stringenum
      required

      Type of webhook event

      values
      • workflow.started
      • workflow.failed
      • workflow.completed
      • workflow.declined
      • workflow.voided
    • mode
      Type: stringenum
      required

      Namespace mode. Critical safety signal — branch on this to guarantee test workflows never mutate your production systems. Same value the namespace was created with.

      values
      • test
      • live
    • namespaceKey
      Type: string
      required

      Namespace the event belongs to. The webhook endpoint that fired this delivery was registered in this (orgId, namespaceKey).

    • orgId
      Type: string Pattern: ^org_[0-9a-z]{26}$
      required

      Organization the event belongs to. Use for routing on the consumer side when one webhook handler URL receives events from multiple SignStack orgs (e.g., across acquisitions or sub-tenant deployments). Prefixed lowercase ULID, e.g. org_01jv8m7qfj6xj9gkz7a4s2h8e.

    • timestamp
      Type: stringFormat: date-time
      required

      When the event fired on the SignStack side. ISO 8601. Distinct from the t= value in the X-Webhook-Signature header (which is the unix-millisecond timestamp the signature was computed against — see Verify webhook signatures for verification details).

  • status
    Type: stringenum

    Delivery state:

    • pending — queued or in-flight; will be retried per the webhook's retry policy on transient failure (timeout, 5xx, network error).
    • success — the customer endpoint returned 2xx on some attempt.
    • failed — every attempt has failed and the retry budget (maxAttempts / maxRetryDuration) is exhausted. The delivery will not be retried further unless explicitly redriven.
    values
    • pending
    • success
    • failed
  • stepKey
    Type: string

    Workflow step key that triggered this event, when applicable (e.g., step.completed, participant.signing_completed). Absent for envelope- or workflow-level events.

  • updatedAt
    Type: stringFormat: date-time

    Last touched timestamp — bumps on every attempt and on status transitions (pending → success / pending → failed). Equal to the most recent attempts[].attemptedAt once at least one attempt has run.

  • webhookEndpointId
    Type: string Pattern: ^we_[0-9a-z]{26}$

    Webhook endpoint this delivery belongs to. Prefixed lowercase ULID, e.g. we_01jv8m7qfj6xj9gkz7a4s2h8e.

  • workflowId
    Type: string Pattern: ^wf_[0-9a-z]{26}$

    ID of the workflow that triggered this event, when applicable. Absent for events not tied to a workflow. Prefixed lowercase ULID, e.g. wf_01jv8m7qfj6xj9gkz7a4s2h8e.