REST API

Webhooks

A webhook endpoint is an HTTPS URL of yours. eSoppari calls it when a signing request changes. The call is signed with the Standard Webhooks scheme, so you can check that it came from us.

Events

The body names the resource and its status, and nothing else:

{
  "type": "signer.signed",
  "timestamp": "2026-10-15T09:00:00Z",
  "data": {
    "object": "signer",
    "id": "8f0c5a8e-2a64-4f6b-9a77-1b0d3f6c2e11",
    "status": "signed",
    "signing_request_id": "1c4b8f3a-6d2e-4a0b-b5c1-3e9f7d2a6b80"
  }
}

Get the details with GET /v1/signing-requests/{id}. A cancelled request has the status declined, the same as GET shows: only the event type tells a cancel from a decline.

Events can arrive out of order, and more than once. Use timestamp to order them, read the current state through the API, and drop a repeat by its webhook-id header.

Register an endpoint

curl -X POST https://api.esoppari.fi/v1/webhook-endpoints \
  -H "Authorization: Bearer $ESOPPARI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/esoppari", "event_types": ["signing_request.completed"]}'

The answer carries secret, which starts with whsec_. It is shown once. Store it beside your API key. Leave out event_types to get every event.

The URL must use https on port 443, with a host name, not an IP address. A host that resolves to a private or loopback address is refused. An organisation has 10 endpoints at most. Administrators can do the same on Settings, Webhooks in the admin portal.

Verify each call

Each call has three headers:

• webhook-id: evt_ and the event id, the same on each retry of one event. To read the event with GET /v1/events/{event_id}, remove evt_;
• webhook-timestamp: Unix seconds, the time of this attempt;
• webhook-signature: v1, and the base64 HMAC-SHA256 of webhook-id.webhook-timestamp.body. The key is the bytes that the base64 part of your secret decodes to.

Refuse a call whose signature does not match, or whose timestamp is more than 5 minutes away from your clock. Check against the raw body bytes, before you parse the JSON. The Standard Webhooks libraries do all of this:

// npm install standardwebhooks
import { Webhook } from "standardwebhooks";
const wh = new Webhook(process.env.ESOPPARI_WEBHOOK_SECRET);
const event = wh.verify(rawBody, headers); // throws on a bad call

# pip install standardwebhooks
from standardwebhooks.webhooks import Webhook
wh = Webhook(os.environ["ESOPPARI_WEBHOOK_SECRET"])
event = wh.verify(raw_body, headers)  # raises on a bad call

// composer require standard-webhooks/standard-webhooks
// The library reads the header names in lower case only.
$headers = array_change_key_case(getallheaders(), CASE_LOWER);
$wh = new \StandardWebhooks\Webhook(getenv('ESOPPARI_WEBHOOK_SECRET'));
$event = $wh->verify($rawBody, $headers); // throws on a bad call

With no library, the check is a few lines:

func verify(secret string, h http.Header, body []byte) bool {
	key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
	if err != nil {
		return false
	}
	ts, err := strconv.ParseInt(h.Get("webhook-timestamp"), 10, 64)
	if err != nil || math.Abs(float64(time.Now().Unix()-ts)) > 300 {
		return false
	}
	mac := hmac.New(sha256.New, key)
	mac.Write([]byte(h.Get("webhook-id") + "." + h.Get("webhook-timestamp") + "."))
	mac.Write(body)
	want := "v1," + base64.StdEncoding.EncodeToString(mac.Sum(nil))
	for _, sig := range strings.Fields(h.Get("webhook-signature")) {
		if hmac.Equal([]byte(sig), []byte(want)) {
			return true
		}
	}
	return false
}

static bool Verify(string secret, string id, string timestamp, string signatures, byte[] body)
{
    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - long.Parse(timestamp)) > 300) return false;
    var key = Convert.FromBase64String(secret.Replace("whsec_", ""));
    using var mac = new HMACSHA256(key);
    var prefix = Encoding.UTF8.GetBytes($"{id}.{timestamp}.");
    var want = "v1," + Convert.ToBase64String(mac.ComputeHash(prefix.Concat(body).ToArray()));
    return signatures.Split(' ').Any(s => CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(s), Encoding.UTF8.GetBytes(want)));
}

Answer with any 2xx within 8 seconds, then do the work. A slow answer counts as a failure.

Retries, failure and resend

Enable the endpoint again with POST /v1/webhook-endpoints/{id}/enable. The deliveries that were still waiting for a retry when it was disabled are cancelled, and no event is recorded for an endpoint while it is disabled. So, after you enable it:

1. Send the failed and cancelled deliveries again with POST /v1/webhook-endpoints/{id}/recover and a since time, or one delivery with POST /v1/webhook-deliveries/{id}/redeliver. Both refuse a disabled endpoint with 409 webhook_endpoint_disabled. One exception: a redeliver of a webhook.test delivery goes to a disabled endpoint, but not after a 410 Gone. A recover sends 1000 deliveries at most, oldest first, and no test delivery: call it again until it answers 0.
2. Read the current state of your requests through the API, for the time the endpoint was disabled.

The delivery log keeps 30 days.

Rotate the secret

POST /v1/webhook-endpoints/{id}/rotate-secret returns a new secret, once. For 24 hours each call carries two signatures in webhook-signature, one with the new secret and one with the old, so you can deploy the new secret without a gap. The libraries above accept either. A second rotation within the 24 hours ends the oldest secret at once.

Test

POST /v1/webhook-endpoints/{id}/test sends a webhook.test event through the normal path, also to an endpoint that is disabled. The answer is the delivery; read its result with GET /v1/webhook-deliveries/{id}. A test makes one attempt, with no retry. While a test of the endpoint waits for its attempt, a new call returns that test, and a redeliver of a test gives 409 webhook_delivery_pending.