WebhookPayload

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
    required

    Stable per-event identifier — same value across retries of the same delivery. Use as your dedup key on the consumer side.

  • 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
    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).

  • 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).