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
| Header | Description |
|---|---|
Content-Type | application/json |
Pepvote-Signature | HMAC-SHA256 signature with timestamp. See Verifying signatures. |
Pepvote-Event-Type | The event type string, e.g. voting_event.started. |
Pepvote-Event-Id | A unique identifier for this event (idempotency key). |
Pepvote-Delivery-Attempt | 1 for the initial attempt, 2+ for retries. |
User-Agent | Pepvote-Webhooks/1.0 |
Payload structure
All events share a consistent envelope:
{
"id": "evt_mt7kry6p_37k4t2lb",
"type": "voting_event.started",
"createdAt": 1756735800000,
"data": { }
}Envelope fields
| Field | Type | Description |
|---|---|---|
id | string | Unique event ID. Use as an idempotency key to avoid processing the same event twice. Format: evt_{timestamp}_{random}. |
type | string | The event type string, matching the Pepvote-Event-Type header. |
createdAt | number | Unix timestamp in milliseconds of when the event was created. |
data | object | Event-specific payload. Fields vary by event type. |
Common data fields
| Field | Present in | Description |
|---|---|---|
id | Most create/update events | The ID of the created or updated resource. |
votingEventId | All events except voting event lifecycle | The voting event this resource belongs to. |
votingEventCode | All events except voting event lifecycle | The voting event's short code. |
Field names use camelCase.
Bulk event payloads
Bulk operations (e.g. voter.bulk_deleted, candidate.bulk_approved) include:
| Field | Type | Description |
|---|---|---|
deletedCount, approvedCount, or revokedCount | number | Total number of affected records. |
ids | string[] | IDs of affected records, capped at 100. |
truncated | boolean | true 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