Webhooks¶

Webhooks are HTTP requests esigna sends to your app when something happens in a signing process. They are not instant and may arrive out of order, and the same event can arrive more than once.

To receive events:

1. Set up an endpoint that checks signatures and answers pings (below).
2. Create a subscription for the events you want.
3. Activate it. Until then it receives nothing.

Your endpoint¶

esigna only calls endpoints that:

• use https:// and a public address: no localhost, private network or link-local addresses, and no user name or password in the URL. The address is checked again on every connection, and redirects are not followed;
• answer within 15 seconds;
• answer a correctly signed request with a 2xx status (the body is ignored);
• answer a request whose signature doesn't verify with 401 Unauthorized.

Headers¶

Each request carries:

Checking the signature¶

Check the signature on every request, before anything else. If no signature verifies, answer 401 Unauthorized.

The signed content is the webhook-id, the webhook-timestamp and the raw request body, joined with periods:

{webhook-id}.{webhook-timestamp}.{body}

Use the body exactly as received. webhook-signature lists signatures as scheme,base64-signature, separated by spaces:

v1,{base64-hmac-sha256} v1a,{base64-ed25519}

Accept the request if any one signature verifies. The list may grow, for example during a key change, so ignore schemes you don't know.

Also refuse requests whose webhook-timestamp is more than about five minutes from your clock, so a captured request can't be replayed later.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

import base64
import hashlib
import hmac
import time

from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives.serialization import load_ssh_public_key

WEBHOOK_SECRET = "3F1C...64 hexadecimal characters"  # from the create response
with open("webhooks-production.pub", "rb") as f:
    ESIGNA_PUBLIC_KEY = load_ssh_public_key(f.read())

def is_from_esigna(headers, body: bytes) -> bool:
    webhook_id = headers["webhook-id"]
    timestamp = headers["webhook-timestamp"]
    if abs(time.time() - int(timestamp)) > 300:
        return False

    signed = f"{webhook_id}.{timestamp}.".encode() + body
    for entry in headers["webhook-signature"].split(" "):
        scheme, _, value = entry.partition(",")
        if scheme == "v1":
            key = bytes.fromhex(WEBHOOK_SECRET)
            expected = hmac.new(key, signed, hashlib.sha256).digest()
            if hmac.compare_digest(expected, base64.b64decode(value)):
                return True
        elif scheme == "v1a":
            try:
                ESIGNA_PUBLIC_KEY.verify(base64.b64decode(value), signed)
                return True
            except InvalidSignature:
                pass
    return False

Public keys¶

esigna's ed25519 public keys, in OpenSSH format:

Duplicates¶

esigna may send the same event more than once, for example when your endpoint handled a request but its answer didn't reach esigna in time. Store the webhook-id of each event you have handled and skip repeats.

Check the signature before looking at webhook-id. Activation and the security checks send requests that must be refused, and a handler that skips "repeats" before checking the signature would answer them with 2xx.

Pings and security checks¶

esigna sends a webhook.ping to every active subscription about once an hour, whether or not it subscribes to webhook.ping. Answer it with 2xx.

At random times, every one to five hours, esigna also sends a security check: a ping signed so that it can't verify, which your endpoint must answer with 401.

• If your endpoint doesn't answer, or answers with an error, esigna tries again every 5 minutes. The account's admins get an email about it, at most one a day.
• After three days in which every ping failed, the subscription is switched off and the admins get an email.
• If your endpoint answers a security check with 2xx, it accepted a request it could not have verified: the subscription is switched off at once and the admins get an email. An outage during a security check doesn't count; the check just waits until your endpoint answers.

A switched-off subscription receives nothing until you activate it again.

Managing subscriptions¶

Creating a subscription¶

POST /api/v1/portal/webhooks

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

import requests

API = "https://api.esigna.is/api/v1"

def create_subscription(token: str):
    r = requests.post(
        f"{API}/portal/webhooks",
        json={
            "url": "https://example.is/esigna-events",
            "eventTypes": ["participant.signed", "participant.declined", "process.completed"],
        },
        headers={"Authorization": f"Bearer {token}"},
    )
    r.raise_for_status()
    return r.json()

1
2
3
4
5
6
7
8

curl https://api.esigna.is/api/v1/portal/webhooks \
  --request POST \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.is/esigna-events",
    "eventTypes": ["participant.signed", "participant.declined", "process.completed"]
  }'

Example response: 201 Created¶

The Location header holds the subscription's address, /api/v1/portal/webhooks/{id}.

1
2
3
4
5
6
7
8

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "url": "https://example.is/esigna-events",
    "secret": "3F1C2D4E5B6A7980...",
    "isActive": false,
    "eventTypes": ["participant.signed", "participant.declined", "process.completed"],
    "createdAt": "2026-10-09T12:00:00Z"
}

A 400 names the problem: a URL that isn't public https://, or an event type that isn't available.

Activating a subscription¶

POST /api/v1/portal/webhooks/{id}/activate

New subscriptions are inactive. Activation sends your endpoint two pings, each with its own webhook-id:

1. one correctly signed, which must get a 2xx;
2. one that can't verify, which must get 401 Unauthorized.

If both pass, the subscription is active and the response is 200 with the subscription. If either fails, or your endpoint can't be reached, the response is 422 Unprocessable Entity and says which check failed:

{
    "error": "Endpoint did not respond with 401 Unauthorized to a ping with an invalid signature."
}

The two pings can take up to 30 seconds. If the subscription's URL is changed while they run, the response is 409 Conflict and the subscription stays inactive: activate it again, so the new URL gets checked.

curl https://api.esigna.is/api/v1/portal/webhooks/$ID/activate \
  --request POST \
  --header "Authorization: Bearer $TOKEN"

Sending a test event¶

POST /api/v1/portal/webhooks/{id}/test

Sends one correctly signed webhook.ping. Returns 204 No Content if your endpoint answered 2xx, and 502 Bad Gateway if it answered anything else, timed out or couldn't be reached.

Listing and getting subscriptions¶

GET /api/v1/portal/webhooks lists your subscriptions; GET /api/v1/portal/webhooks/{id} returns one, or 404. Neither returns the secret.

1
2
3
4
5
6
7
8

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "url": "https://example.is/esigna-events",
    "isActive": true,
    "eventTypes": ["participant.signed", "participant.declined", "process.completed"],
    "createdAt": "2026-10-09T12:00:00Z",
    "updatedAt": "2026-10-09T12:05:00Z"
}

Updating a subscription¶

PUT /api/v1/portal/webhooks/{id}

Send only the fields you want to change.

Returns 200 with the subscription, 400 for a URL or event type that isn't allowed, or 404.

Deleting a subscription¶

DELETE /api/v1/portal/webhooks/{id} deletes the subscription for good. Returns 204 No Content, or 404.

Delivery and retries¶

Events come from the signing processes your account created through the API; documents sent from the esigna web app send none. esigna sends each event to the subscriptions that include its type and are active when it is first sent, normally within seconds of it happening: a subscription created or activated later doesn't get earlier events.

If your endpoint doesn't answer 2xx within 15 seconds, the event is sent again, to that subscription only:

So an event is retried for about a day and a half. If your endpoint was down for longer, read the signing process's status to catch up.

Events¶

Every event body has the same shape: a type, a timestamp and a data object.

kennitala and phone are empty strings when esigna doesn't know them.

participant.signed¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
    "type": "participant.signed",
    "timestamp": "2026-10-09T13:58:49.407+00:00",
    "data": {
        "signingProcessId": "c93e6bf4-a256-4b97-9abb-c7650cdc87f5",
        "participant": {
            "name": "Jón Jónsson",
            "email": "jon@example.is",
            "kennitala": "0101302989",
            "phone": "",
            "signature": "HiI76ZWOyHP98jqXs6QOvrDK...",
            "signedAt": "2026-10-09T13:58:49.407+00:00"
        }
    }
}

participant.declined¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
    "type": "participant.declined",
    "timestamp": "2026-10-09T13:58:49.407+00:00",
    "data": {
        "signingProcessId": "c93e6bf4-a256-4b97-9abb-c7650cdc87f5",
        "participant": {
            "name": "Jón Jónsson",
            "email": "jon@example.is",
            "kennitala": "0101302989",
            "phone": "",
            "declineReason": "Rangt nafn á samningnum",
            "declinedAt": "2026-10-09T13:58:49.407+00:00"
        }
    }
}

process.completed¶

Sent when every signer has signed. The event doesn't carry the document: download the signed document with the signingProcessId.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
    "type": "process.completed",
    "timestamp": "2026-10-09T14:58:50.407+00:00",
    "data": {
        "signingProcessId": "c93e6bf4-a256-4b97-9abb-c7650cdc87f5",
        "participants": [
            {
                "name": "Jón Jónsson",
                "email": "jon@example.is",
                "kennitala": "0101302989",
                "phone": "",
                "signature": "HiI76ZWOyHP9...",
                "signedAt": "2026-10-09T13:58:49.407+00:00"
            }
        ]
    }
}

webhook.ping¶

1
2
3
4
5

{
    "type": "webhook.ping",
    "timestamp": "2026-10-09T13:58:49.407+00:00",
    "data": {}
}