Download the PHP package jeffersongoncalves/laravel-zapsign without Composer

Laravel ZapSign

Laravel client for the ZapSign e-signature REST API: documents, templates, signers and webhooks — rate-limit aware out of the box, with database persistence and queued jobs.

ZapSign allows 500 requests per minute per token/IP and answers 429 above that. This package:

• throttles requests client-side through your cache store, so every worker sharing the store stays under the limit;
• waits for a free slot (up to max_wait seconds) instead of failing, or throws a RateLimitException you can use to release() a queued job;
• retries any 429/503 that still reaches the API with exponential backoff, honouring Retry-After (never timeouts/502, which could create a document twice);
• queued jobs release themselves on a rate limit instead of failing.

Documents and signers can be stored in your database and kept up to date by queued jobs and webhooks, and signed PDFs copied to any filesystem disk before ZapSign's 60-minute links expire.

Installation

Publish the config and migrations, then migrate (creates zapsign_documents, zapsign_signers and zapsign_webhook_calls):

Add your API token (ZapSign > Settings > Integration > ZapSign API):

Usage

Every method returns the decoded JSON response as an array. Request bodies follow the ZapSign docs field names as-is.

Errors

Database and jobs

Models

Document::sync(array $data, ?Model $documentable = null) upserts any document array returned by the API or a webhook (same shape) with its signers — signers missing from the payload are removed — so you can store results of your own calls too.

Jobs

• On a rate limit the jobs release() themselves for the Retry-After time ($tries = 10).
• CreateDocument is not retried after an error ($maxExceptions = 1): the document may already exist at ZapSign and credits may be spent.
• SyncDocument is unique per document for 60 s, so bursts collapse into one request.
• StoreSignedFile downloads the signed PDF to ZAPSIGN_FILES_DISK (ZAPSIGN_FILES_DIRECTORY/{token}.pdf) and saves signed_file_path; it is queued automatically when a webhook marks a document signed, or dispatch it yourself: StoreSignedFile::dispatch($document).
• Set ZAPSIGN_QUEUE_CONNECTION / ZAPSIGN_QUEUE to run them on a dedicated queue.

Rate limit in your own jobs

The client already waits for a free slot. In your own jobs, keep max_wait small and release the job instead of blocking the worker:

Use a shared store (Redis, database) when you run several servers/workers — the array or file store only limits a single process/host.

Webhooks

ZapSign does not sign webhook requests, so the endpoint is protected by a secret header that you register together with the webhook:

Register https://your-app.com/zapsign/webhook in ZapSign (Settings > Integration > Webhooks) with a custom header X-ZapSign-Secret: a-long-random-string, or via the API:

The POST /zapsign/webhook route (name zapsign.webhook) is registered only when a secret is set. It:

1. checks the secret header (403 otherwise);
2. stores the call in zapsign_webhook_calls — once per body (ZapSign sends no event id and redelivers until it gets a 200), so duplicate deliveries are ignored;
3. answers 200 right away and queues ProcessWebhookCall, which upserts the document and its signers from the body, soft-deletes on doc_deleted, queues StoreSignedFile when the document is signed and a disk is configured, and finally dispatches WebhookReceived.

The route has no web middleware, so CSRF does not apply. Schedule php artisan model:prune to remove stored calls older than ZAPSIGN_WEBHOOK_PRUNE_AFTER_DAYS (30).

The listener runs after the local tables are updated. $event->payload holds the full body.

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

License

The MIT License (MIT). Please see License File for more information.