{"id":79166,"plugin_id":"plugin_asdk_app_6ad8a84c81cc8191b143b974ae0529ac","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-03T19:24:48.094Z","digest":"88bd1727f6cba11fb8eeaed1ed3e9cb5d027d08400de778217f807b0d75e39fb","against":null,"payload":{"description":"Use when an existing SignatureAPI integration misbehaves. Covers an envelope stuck in processing, a missing webhook or signing email, an invalid or expired link, a missing signed document, or a 4xx error. Use it even for one missing email; test mode never sends real email. Read-only; safe on live envelopes.","included_files":[{"relative_path":"package-lock.json","size_in_bytes":698},{"relative_path":"package.json","size_in_bytes":131},{"relative_path":"references/errors.md","size_in_bytes":1707},{"relative_path":"scripts/diagnose-envelope.mjs","size_in_bytes":5400},{"relative_path":"scripts/lib/output.mjs","size_in_bytes":3997}],"name":"signatureapi-diagnose","skill_md_contents":"---\nname: signatureapi-diagnose\ndescription: \"Use when an existing SignatureAPI integration misbehaves. Covers an envelope stuck in processing, a missing webhook or signing email, an invalid or expired link, a missing signed document, or a 4xx error. Use it even for one missing email; test mode never sends real email. Read-only; safe on live envelopes.\"\nallowed-tools: Read, Grep, WebFetch(domain:signatureapi.com), WebFetch(domain:spec.signatureapi.com)\ninputs:\n  - name: SIGNATUREAPI_KEY\n    required: true\n---\n\n# Troubleshoot SignatureAPI\n\nStart here: `node scripts/diagnose-envelope.mjs --envelope <id>`. It fetches\nthe envelope and its events in one pass and prints a verdict with next steps.\n\n## When to reach for something else\n\n- **Deciding how an app should use SignatureAPI** belongs to\n  `signatureapi-architecture`.\n- **Building a new signing flow** (creating envelopes, placing signature\n  fields, wiring up a webhook for the first time) belongs to\n  `signatureapi-integrate`.\n- **How SignatureAPI is documented to behave** belongs to\n  `signatureapi-docs`. Use it to compare an envelope's state with the\n  documented behavior.\n- **A webhook that is not a SignatureAPI webhook** belongs to whatever sent\n  it. The symptoms and event shapes below are specific to SignatureAPI.\n- **A different e-signature vendor** (DocuSign, Dropbox Sign, Adobe Sign,\n  etc.) needs that vendor's own docs. The failure codes and symptoms here\n  are SignatureAPI-specific.\n- **A project with no SignatureAPI credentials present** has no envelope to\n  diagnose yet. Confirm that first. Do not run this skill's scripts against\n  a key that does not exist.\n\n## Access\n\nThese are your tools for reading state. The customer's application does not\ndepend on them. The application integrates against the REST API\n(`https://api.signatureapi.com/v1`, header `X-API-Key`). While diagnosing,\nuse MCP first (`https://mcp.signatureapi.com/mcp`): `whoami`, `get_envelope`\n(takes `envelope_id`, not `id`), `list_envelopes`, `list_events`,\n`list_webhooks`, `list_webhook_attempts`, `get_deliverables`, `list_emails`,\n`get_email`. Reads by id work on test and live\nenvelopes alike. Listings take a per-call `mode` and default to test;\n`whoami.modes.live` indicates access, not a session mode. Call `whoami`\nonly for an account question or a needed live-access check. Fall back to REST when a tool is missing. For documented behavior, use\n`signatureapi-docs`. When you have to fall\nback, report the gap at https://github.com/signatureapi/skills/issues/new.\n\nIdentifiers named below (paths, event types, status codes) are illustrations.\nThe published spec at `https://spec.signatureapi.com/openapi.yaml` is the\nsource of truth, and wins if the two disagree.\n\nThis skill only reads. Every script issues GET requests, so it is safe\nagainst a live key during an incident. Each script reports the mode it ran\nin. Run a script with `node --env-file=<project env file> scripts/…` so the\nkey loads without being printed.\n\nThe repair is a separate decision. Once the verdict is clear, name the fix\nand ask before applying it. `resend_request` for a signer who lost the\nemail. `replace_recipient` for a bounced or wrong address. `create_ceremony`\nfor an expired link. In live mode each one emails a real person.\n\nRead `SIGNATUREAPI_KEY` from the environment only. Never pass it as a\ncommand-line argument. Argv is exposed in shell history and process listings\non any shared or logged system.\n\n## Symptoms\n\n### Envelope stuck in `processing`\nDocuments are still being fetched and prepared. Almost always an unreachable\ndocument URL. Check two things: does every document URL return 200 to an\nanonymous request, and is each file a valid PDF or DOCX?\n\n### No webhook arrived\nSplit the question in two. Did the event happen? `list_events` with the\n`envelope_id`, or `GET /envelopes/{envelopeId}/events`. Was it delivered?\n`list_webhook_attempts` for the endpoint shows each delivery and the\nresponse code your handler returned. No attempt means the endpoint is not\nsubscribed to that event type, or is in the other mode. A non-2xx attempt\nmeans your handler ran and failed. A 401 or 400 on every attempt usually\nmeans signature verification fails. Check three things: the handler\nverifies the raw body, not re-serialized JSON; it reads the `webhook-id`,\n`webhook-timestamp` and `webhook-signature` headers; and its secret belongs\nto this endpoint and mode. Test and live endpoints are separate. A\ntest envelope never notifies a live endpoint.\n\n### Recipient never got the email\nIn **test mode no email is ever sent**. That is by design. Read what would\nhave been sent with `list_emails`, then `get_email`. Only test signing-request emails expose rendered content and ceremony\nlinks. Authentication-code subjects and content are withheld. In live mode, look for\n`recipient.soft_bounced` / `recipient.hard_bounced` events.\n\n### Ceremony link does not work\nLinks are single-recipient and expire. For `email_link` recipients the link\nis the authentication. So the API never returns it in live mode. Only the\ntest-mode email log exposes it.\n\n### Deliverable missing after completion\nCheck for a `deliverable.generated` event, then `get_deliverables` (or\n`GET /envelopes/{envelopeId}/deliverables`). A `pending` or `processing`\nstatus means not yet, not missing.\n\n### \"Invalid link\" or an expired link\nCreating a ceremony revokes every earlier link for that recipient. Look for\ncode that creates ceremonies more than once: a retried webhook handler, or\nan email scanner opening a link that creates one on open. Links also expire,\nafter 30 days by default. The fix is a fresh link (`create_ceremony` or a\nresend). Ask before applying it.\n\n### Envelope creation rejects the document\n- The URL host is not a supported storage host: upload the file instead.\n- \"Could not be parsed as a PDF\" on a DOCX: `format` is missing.\n- A DOCX from Google Docs, LibreOffice or a DOCX library fails to parse:\n  re-save it in Microsoft Word.\n- A placeholder is \"not found\" in a PDF printed from HTML: ligatures or\n  zero-width characters split the marker text.\n\n### 422 on create\nSee `references/errors.md` for the response shape and the most common cause.\nCheck the exact schema in the OpenAPI spec at\n`https://spec.signatureapi.com/openapi.yaml`.\n\n## References\n\n- `references/errors.md` — HTTP status codes and what they mean here\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}