Pepvote Support Center
Webhooks

Payload format

The structure of webhook HTTP requests and JSON payloads for every event type.

Every webhook delivery is an HTTP POST request with a JSON body.

Request headers

HeaderDescription
Content-Typeapplication/json
Pepvote-SignatureHMAC-SHA256 signature with timestamp. See Verifying signatures.
Pepvote-Event-TypeThe event type string, e.g. voting_event.started.
Pepvote-Event-IdA unique identifier for this event (idempotency key).
Pepvote-Delivery-Attempt1 for the initial attempt, 2+ for retries.
User-AgentPepvote-Webhooks/1.0

Payload structure

All events share a consistent envelope:

{
  "id": "evt_mt7kry6p_37k4t2lb",
  "type": "voting_event.started",
  "createdAt": 1756735800000,
  "data": { }
}

Envelope fields

FieldTypeDescription
idstringUnique event ID. Use as an idempotency key to avoid processing the same event twice. Format: evt_{timestamp}_{random}.
typestringThe event type string, matching the Pepvote-Event-Type header.
createdAtnumberUnix timestamp in milliseconds of when the event was created.
dataobjectEvent-specific payload. Fields vary by event type.

Common data fields

FieldPresent inDescription
idMost create/update eventsThe ID of the created or updated resource.
votingEventIdAll events except voting event lifecycleThe voting event this resource belongs to.
votingEventCodeAll events except voting event lifecycleThe voting event's short code.

Field names use camelCase.

Bulk event payloads

Bulk operations (e.g. voter.bulk_deleted, candidate.bulk_approved) include:

FieldTypeDescription
deletedCount, approvedCount, or revokedCountnumberTotal number of affected records.
idsstring[]IDs of affected records, capped at 100.
truncatedbooleantrue when the actual count exceeds 100 and the ids array was cut short.

All event payloads

voting_event.created

{
  "id": "evt_mt7kry6p_37k4t2lb",
  "type": "voting_event.created",
  "createdAt": 1756731600000,
  "data": {
    "id": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "title": "Board Election 2026",
    "code": "EHYBT7452",
    "type": "election",
    "status": "draft",
    "createdBy": "k574a00w8zxh753v4k25nn5xt58aykw5"
  }
}

voting_event.updated

{
  "id": "evt_mt7ksa3q_r2n8v4wd",
  "type": "voting_event.updated",
  "createdAt": 1756735200000,
  "data": {
    "id": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "code": "EHYBT7452",
    "title": "Board Election 2026",
    "type": "election",
    "status": "active",
    "startsAt": 1756735800000,
    "endsAt": 1756822200000
  }
}

voting_event.started

{
  "id": "evt_mt7kt4bp_a5g7h2xm",
  "type": "voting_event.started",
  "createdAt": 1756747800000,
  "data": {
    "id": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "code": "EHYBT7452",
    "title": "Board Election 2026",
    "startsAt": 1756735800000
  }
}

voting_event.ended

{
  "id": "evt_mt7lw5cr_b3f9k6yn",
  "type": "voting_event.ended",
  "createdAt": 1756735800000,
  "data": {
    "id": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "code": "EHYBT7452",
    "title": "Board Election 2026",
    "endsAt": 1756822200000
  }
}

voting_event.locked

{
  "id": "evt_mt7mx6ds_c4g0l7zp",
  "type": "voting_event.locked",
  "createdAt": 1756735800000,
  "data": {
    "id": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "code": "EHYBT7452"
  }
}

voting_event.deleted

{
  "id": "evt_mt7ny7et_d5h1m8aq",
  "type": "voting_event.deleted",
  "createdAt": 1756735800000,
  "data": {
    "id": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "code": "EHYBT7452",
    "title": "Board Election 2026"
  }
}

vote.cast

{
  "id": "evt_mt7s2a1q_x9f3h7pn",
  "type": "vote.cast",
  "createdAt": 1756748100000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "voterId": "jd74a00w8zxh753v4k25nn5xt58aykw5",
    "voterEmail": "jane@example.com",
    "visitorId": null,
    "positionCount": 3,
    "channel": "web"
  }
}

For polls, voterEmail may be null and visitorId contains the browser-generated visitor identifier:

{
  "id": "evt_mt7s3b2r_y8g4j9qn",
  "type": "vote.cast",
  "createdAt": 1756748400000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "POLLX1234",
    "voterId": "kw92b11x9ayj864w5l36oo6yu69bzlx6",
    "voterEmail": null,
    "visitorId": "visitor_a1b2c3d4e5f6",
    "positionCount": 1,
    "channel": "web"
  }
}

vote.confirmed

{
  "id": "evt_mt7s3b2r_y0g4i8qo",
  "type": "vote.confirmed",
  "createdAt": 1756748160000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "voterId": "jd74a00w8zxh753v4k25nn5xt58aykw5",
    "confirmationCode": "ABC123",
    "positionCount": 3
  }
}

vote.recount_started

{
  "id": "evt_mt7t4c3s_z1h5j9rp",
  "type": "vote.recount_started",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452"
  }
}

vote.recount_completed

{
  "id": "evt_mt7t5d4t_a2i6k0sq",
  "type": "vote.recount_completed",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452"
  }
}

vote.exported

{
  "id": "evt_mt7u6e5u_b3j7l1tr",
  "type": "vote.exported",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "recordCount": 542
  }
}

vote.export_failed

{
  "id": "evt_mt7u7f6v_c4k8m2us",
  "type": "vote.export_failed",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "reason": "Storage write failed after 200 rows."
  }
}

voter.created

{
  "id": "evt_mt7v8g7w_d5l9n3vt",
  "type": "voter.created",
  "createdAt": 1756735800000,
  "data": {
    "id": "jn482xqt7rw0kp6a3ydv5mcbse9f1hgz",
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "name": "Jane Smith",
    "email": "jane@example.com"
  }
}

voter.updated

{
  "id": "evt_mt7v9h8x_e6m0o4wu",
  "type": "voter.updated",
  "createdAt": 1756735800000,
  "data": {
    "id": "jn482xqt7rw0kp6a3ydv5mcbse9f1hgz",
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "name": "Jane A. Smith",
    "email": "jane@example.com"
  }
}

voter.imported

{
  "id": "evt_mt7w0i9y_f7n1p5xv",
  "type": "voter.imported",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "importedCount": 250,
    "skippedCount": 3
  }
}

voter.import_failed

{
  "id": "evt_mt7w1j0z_g8o2q6yw",
  "type": "voter.import_failed",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "reason": "Duplicate email found at row 45.",
    "succeededCount": 44
  }
}

voter.bulk_deleted

{
  "id": "evt_mt7w2k1a_h9p3r7zx",
  "type": "voter.bulk_deleted",
  "createdAt": 1756731600000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "deletedCount": 15,
    "ids": ["jn482xqt7rw0kp6a3ydv5mcbse9f1hgz", "qr593yas8sx1lq7b4zew6ndcte0g2ihb"],
    "truncated": false
  }
}

voter.bulk_approved

{
  "id": "evt_mt7w3l2b_i0q4s8ay",
  "type": "voter.bulk_approved",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "ids": ["jn482xqt7rw0kp6a3ydv5mcbse9f1hgz"],
    "truncated": false
  }
}

voter.exported

{
  "id": "evt_mt7w4m3c_j1r5t9bz",
  "type": "voter.exported",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "recordCount": 250
  }
}

voter.export_failed

{
  "id": "evt_mt7w5n4d_k2s6u0ca",
  "type": "voter.export_failed",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "reason": "File storage quota exceeded."
  }
}

candidate.created

{
  "id": "evt_mt7x6o5e_l3t7v1db",
  "type": "candidate.created",
  "createdAt": 1756735200000,
  "data": {
    "id": "wd826bfr3hn5ks9e7yat0pgcxj4m1lqv",
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "name": "John Doe",
    "positionId": "tp914cgs4io6lt0f8zbu1qhdy5kn2mrw"
  }
}

candidate.updated

{
  "id": "evt_mt7x7p6f_m4u8w2ec",
  "type": "candidate.updated",
  "createdAt": 1756735800000,
  "data": {
    "id": "wd826bfr3hn5ks9e7yat0pgcxj4m1lqv",
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "name": "John A. Doe"
  }
}

candidate.imported

{
  "id": "evt_mt7x8q7g_n5v9x3fd",
  "type": "candidate.imported",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "importedCount": 12,
    "skippedCount": 1
  }
}

candidate.bulk_deleted

{
  "id": "evt_mt7x9r8h_o6w0y4ge",
  "type": "candidate.bulk_deleted",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "deletedCount": 5,
    "ids": ["wd826bfr3hn5ks9e7yat0pgcxj4m1lqv"],
    "truncated": false
  }
}

candidate.bulk_approved

{
  "id": "evt_mt7y0s9i_p7x1z5hf",
  "type": "candidate.bulk_approved",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "ids": ["wd826bfr3hn5ks9e7yat0pgcxj4m1lqv"],
    "truncated": false
  }
}

position.created

{
  "id": "evt_mt7z1t0j_q8y2a6ig",
  "type": "position.created",
  "createdAt": 1756735800000,
  "data": {
    "id": "tp914cgs4io6lt0f8zbu1qhdy5kn2mrw",
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "title": "President",
    "votingMethod": "plurality"
  }
}

position.updated

{
  "id": "evt_mt7z2u1k_r9z3b7jh",
  "type": "position.updated",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "title": "President",
    "votingMethod": "ranked_choice"
  }
}

position.imported

{
  "id": "evt_mt7z3v2l_s0a4c8ki",
  "type": "position.imported",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "importedCount": 6,
    "skippedCount": 0
  }
}

position.bulk_deleted

{
  "id": "evt_mt7z4w3m_t1b5d9lj",
  "type": "position.bulk_deleted",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "deletedCount": 2,
    "ids": ["tp914cgs4io6lt0f8zbu1qhdy5kn2mrw"],
    "truncated": false
  }
}

group.created

{
  "id": "evt_mt804x4n_u2c6e0mk",
  "type": "group.created",
  "createdAt": 1756735800000,
  "data": {
    "id": "gp371dhv5jp8mu2g0acw3riexl6o4nsb",
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "name": "Engineering Department"
  }
}

group.updated

{
  "id": "evt_mt805y5o_v3d7f1nl",
  "type": "group.updated",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "name": "Engineering & Design"
  }
}

group.imported

{
  "id": "evt_mt806z6p_w4e8g2om",
  "type": "group.imported",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "importedCount": 4,
    "skippedCount": 0
  }
}

group.bulk_deleted

{
  "id": "evt_mt807a7q_x5f9h3pn",
  "type": "group.bulk_deleted",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "deletedCount": 2,
    "ids": ["gp371dhv5jp8mu2g0acw3riexl6o4nsb"],
    "truncated": false
  }
}

sponsor.created

{
  "id": "evt_mt808b8r_y6g0i4qo",
  "type": "sponsor.created",
  "createdAt": 1756735800000,
  "data": {
    "id": "sp593eiw6kq9nv3h1bdc4sjfym7p5otc",
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "name": "Acme Corp"
  }
}

sponsor.updated

{
  "id": "evt_mt809c9s_z7h1j5rp",
  "type": "sponsor.updated",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "name": "Acme Corporation"
  }
}

sponsor.imported

{
  "id": "evt_mt810d0t_a8i2k6sq",
  "type": "sponsor.imported",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "importedCount": 3,
    "skippedCount": 0
  }
}

sponsor.bulk_deleted

{
  "id": "evt_mt811e1u_b9j3l7tr",
  "type": "sponsor.bulk_deleted",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "deletedCount": 1,
    "ids": ["sp593eiw6kq9nv3h1bdc4sjfym7p5otc"],
    "truncated": false
  }
}

registration.voter_registered

{
  "id": "evt_mt812f2v_c0k4m8us",
  "type": "registration.voter_registered",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "voterId": "hw92c22y0bzk975x6m47pp7zv70cylz7",
    "name": "Alex Johnson",
    "email": "alex@example.com"
  }
}

registration.candidate_registered

{
  "id": "evt_mt813g3w_d1l5n9vt",
  "type": "registration.candidate_registered",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "candidateId": "lx83d33z1cak086y7n58qq8aw81damb8",
    "name": "Sam Williams"
  }
}

registration.voter_registration_closed

{
  "id": "evt_mt814h4x_e2m6o0wu",
  "type": "registration.voter_registration_closed",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "closedAt": 1756735800000
  }
}

registration.candidate_registration_closed

{
  "id": "evt_mt815i5y_f3n7p1xv",
  "type": "registration.candidate_registration_closed",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "closedAt": 1756735800000
  }
}

pricing.vote_pricing_updated

{
  "id": "evt_mt816j6z_g4o8q2yw",
  "type": "pricing.vote_pricing_updated",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452"
  }
}

pricing.candidate_registration_pricing_updated

{
  "id": "evt_mt817k7a_h5p9r3zx",
  "type": "pricing.candidate_registration_pricing_updated",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452"
  }
}

pricing.quadratic_credit_pricing_updated

{
  "id": "evt_mt818l8b_i6q0s4ay",
  "type": "pricing.quadratic_credit_pricing_updated",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452"
  }
}

payment.succeeded

{
  "id": "evt_mt819m9c_j7r1t5bz",
  "type": "payment.succeeded",
  "createdAt": 1756748400000,
  "data": {
    "id": "pa604fjx7lr0ow4i2cfe5tkgzn8q6pub",
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "amount": 50000,
    "currency": "NGN",
    "provider": "paystack",
    "purpose": "vote"
  }
}

payment.failed

{
  "id": "evt_mt820n0d_k8s2u6ca",
  "type": "payment.failed",
  "createdAt": 1756735800000,
  "data": {
    "id": "pa715gky8ms1px5j3dgf6ulhao9r7qvc",
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "amount": 50000,
    "currency": "NGN",
    "provider": "paystack",
    "purpose": "vote",
    "reason": "Card declined by issuing bank."
  }
}

invite.sent

{
  "id": "evt_mt821o1e_l9t3v7db",
  "type": "invite.sent",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "role": "observer",
    "insertedCount": 3
  }
}

invite.accepted

{
  "id": "evt_mt822p2f_m0u4w8ec",
  "type": "invite.accepted",
  "createdAt": 1756735800000,
  "data": {
    "id": "iv826bqs3hn5kt9e7yau0pgcxj4m1lrw",
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "email": "observer@example.com",
    "role": "observer"
  }
}

invite.revoked

{
  "id": "evt_mt823q3g_n1v5x9fd",
  "type": "invite.revoked",
  "createdAt": 1756731600000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "revokedCount": 2,
    "ids": ["iv826bqs3hn5kt9e7yau0pgcxj4m1lrw", "iv937crt4io6lu0f8zbu1rhfyk5n2msw"],
    "truncated": false
  }
}

plan.upgraded

{
  "id": "evt_mt824r4h_o2w6y0ge",
  "type": "plan.upgraded",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "previousPlan": "free",
    "newPlan": "starter"
  }
}

plan.voter_limit_increased

{
  "id": "evt_mt825s5i_p3x7z1hf",
  "type": "plan.voter_limit_increased",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452",
    "previousLimit": 150,
    "newLimit": 500
  }
}

result.published

{
  "id": "evt_mt826t6j_q4y8a2ig",
  "type": "result.published",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452"
  }
}

result.recount_started

{
  "id": "evt_mt827u7k_r5z9b3jh",
  "type": "result.recount_started",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452"
  }
}

result.recount_completed

{
  "id": "evt_mt828v8l_s6a0c4ki",
  "type": "result.recount_completed",
  "createdAt": 1756735800000,
  "data": {
    "votingEventId": "mx757dzmehw9xvva8y6mbyfttd8d3nqb",
    "votingEventCode": "EHYBT7452"
  }
}
Was this helpful?

Last updated August 25, 2026

On this page