X Enterprises
fastify-x-signwell

xsignwell.webhooks.parseEvent

Parse a raw SignWell webhook payload into a structured event object, and reference available event type constants.

xsignwell.webhooks.parseEvent

Parse a raw SignWell webhook payload into a structured object with normalized fields. The webhooks.events constants object provides string values for all supported event types.

Signature

fastify.xsignwell.webhooks.parseEvent(
  payload: Record<string, unknown>
): {
  event: string;
  documentId: string;
  document: Object;
  recipient: Object | undefined;
  timestamp: string;
  raw: Object;
}

Params

NameTypeRequiredDescription
payloadobjectYesParsed JSON body from the webhook request.

Returns

{
  event: string;       // event type, e.g. "document.completed"
  documentId: string;  // extracted document ID
  document: Object;    // full document object from payload
  recipient: Object;   // recipient object (present for recipient.* events)
  timestamp: string;   // event timestamp or current ISO time
  raw: Object;         // original unmodified payload
}

Throws

  • [xSignwell] webhooks.parseEvent: payload (object) is required

webhooks.events constants

The fastify.xsignwell.webhooks.events object provides string constants for all SignWell event types:

ConstantValue
DOCUMENT_COMPLETED"document.completed"
DOCUMENT_SENT"document.sent"
DOCUMENT_VIEWED"document.viewed"
DOCUMENT_SIGNED"document.signed"
DOCUMENT_DECLINED"document.declined"
DOCUMENT_EXPIRED"document.expired"
DOCUMENT_VOIDED"document.voided"
RECIPIENT_COMPLETED"recipient.completed"
RECIPIENT_VIEWED"recipient.viewed"
RECIPIENT_SIGNED"recipient.signed"
RECIPIENT_DECLINED"recipient.declined"

Examples

Parse and handle an event

const event = fastify.xsignwell.webhooks.parseEvent(request.body);

if (event.event === fastify.xsignwell.webhooks.events.DOCUMENT_COMPLETED) {
  console.log("Document completed:", event.documentId, "at", event.timestamp);
}

Realistic — full webhook handler with verification and routing

fastify.post("/webhooks/signwell", {
  config: { rawBody: true }, // requires rawBody plugin or equivalent
}, async (request, reply) => {
  const signature = request.headers["x-signwell-signature"];
  const rawBody = request.rawBody;

  const isValid = fastify.xsignwell.webhooks.verifySignature(
    rawBody,
    signature,
    process.env.SIGNWELL_WEBHOOK_SECRET
  );

  if (!isValid) {
    return reply.code(401).send({ error: "Invalid signature" });
  }

  const event = fastify.xsignwell.webhooks.parseEvent(request.body);

  if (event.event === fastify.xsignwell.webhooks.events.DOCUMENT_COMPLETED) {
    await db.contracts.update(
      { documentId: event.documentId },
      { status: "completed", completedAt: event.timestamp }
    );
  }

  if (event.event === fastify.xsignwell.webhooks.events.DOCUMENT_DECLINED) {
    await db.contracts.update(
      { documentId: event.documentId },
      { status: "declined" }
    );
  }

  return reply.send({ received: true });
});

See also

AI Context

package: "@xenterprises/fastify-xsignwell"
method: fastify.xsignwell.webhooks.parseEvent(payload)
use-when: Parse a raw SignWell webhook payload into a structured event object after verifying the signature
params: payload (parsed JSON body object)
returns: "{ event, documentId, document, recipient, timestamp, raw }"
events-constants: fastify.xsignwell.webhooks.events — DOCUMENT_COMPLETED, DOCUMENT_SENT, DOCUMENT_VIEWED, DOCUMENT_SIGNED, DOCUMENT_DECLINED, DOCUMENT_EXPIRED, DOCUMENT_VOIDED, RECIPIENT_COMPLETED, RECIPIENT_VIEWED, RECIPIENT_SIGNED, RECIPIENT_DECLINED

xsignwell.webhooks.list

Retrieve all registered SignWell webhook endpoints for the account.

xsignwell.webhooks.verifySignature

Verify the HMAC-SHA256 signature on an incoming SignWell webhook request using timing-safe comparison.

Copyright © 2026