Webhooks let Simply Voting notify your own system each time an elector votes in any election in your account. You can use them, for example, to update a membership database or CRM as votes come in, without having to export data from the Election Manager.
Webhooks are available on all accounts. Only super users can access the Integrations section of the Settings page.
What webhooks send
Each time an elector votes, Simply Voting creates a vote event. Vote events are created for votes from every voting channel, including the voting website, kiosk voting, Manual Vote Entry and telephone voting.
Each vote event includes the Election ID, the Elector ID and the time of the vote. If the Custom 1, Custom 2 and Custom 3 fields are enabled on your account, their values for that elector are also included.
Ballot selections are never included. Webhooks tell your system that an elector has voted, not how they voted.
Because webhooks cover every election in your account, your system may receive events from several elections at once, for example when you run simultaneous elections. Use the Election ID in each event to tell them apart.
Before you begin
Setting up webhooks requires an endpoint on your side: a URL on your server or service that can receive the vote events. This is usually set up by your IT team or the provider of your membership system. Your endpoint must:
Be reachable from the internet at a URL starting with
https, with a valid SSL certificate.Accept
POSTrequests with a JSON payload.Respond quickly with a successful status code (
2xx) when it receives a request.Verify each request using the signing secret provided in the Election Manager.
The technical details your developers need are in the Webhooks API documentation. See About the API documentation below for an overview of what it covers.
Setting up webhooks
In the Election Manager, click Settings in the top menu, then click Integrations under Advanced in the left-hand menu. The Webhooks panel shows the status Not configured.
Under Signing Secret, click the copy button to copy the secret to your clipboard. You can also click the eye icon to show or hide it.
Add the signing secret to your endpoint. Your endpoint uses it to confirm that each request genuinely comes from Simply Voting. Do this before testing: the test request is signed, and your endpoint needs the secret to verify it.
In the Webhook URL field, enter your endpoint's URL. It must start with
https.Click Test & Save.
Simply Voting sends a test request to your endpoint. If your endpoint responds successfully, the message “Test event delivered. Webhooks configuration saved.” appears and the status changes to Active. From then on, new vote events are sent to your endpoint.
Keep your signing secret confidential. Anyone who has it could send requests to your endpoint that appear to come from Simply Voting. Share it only with the people who set up and maintain your endpoint.
About the test request
The test request contains two sample vote events with an Election ID of 0. This value identifies test events, not real votes. Your endpoint should verify the request as usual and respond successfully, without recording any votes and without expecting an election with that ID to exist.
A test request is also sent each time you save a new or changed Webhook URL.
If the test fails
If your endpoint doesn't respond successfully, an error message appears and your settings aren't saved. The message tells you what went wrong:
Error message | What to check |
|---|---|
Webhook test failed: your endpoint responded with HTTP [code]. Your settings were not saved. | Your endpoint received the request but rejected it. Check that it accepts |
Webhook test failed: your endpoint did not respond within [number] seconds. Your settings were not saved. | Your endpoint took too long to respond. It should send a successful response right away, before doing any time-consuming processing. |
Webhook test failed: your endpoint could not be reached (connection or SSL certificate error). Your settings were not saved. | Check that the URL is correct, that your endpoint is reachable from the internet, and that its SSL certificate is valid. |
Once the problem is fixed, click Test & Save again.
Changing the Webhook URL
To send vote events to a different endpoint, add the signing secret to the new endpoint, enter its URL in the Webhook URL field, then click Test & Save. The new URL is saved only if the test succeeds.
Disabling webhooks
On the Integrations page, click Disable Webhooks.
In the confirmation dialog, click Disable.
The message Webhooks disabled. appears and the status returns to Not configured. Vote events are no longer sent, and the Webhook URL is removed. The signing secret doesn't change.
To turn webhooks back on, follow the steps in Setting up webhooks: enter the Webhook URL again, then click Test & Save.
How vote events are delivered
Vote events aren't sent one by one as votes are cast. Simply Voting groups the events from the past minute and sends them to your endpoint in a single request, once per minute. Because of this batching, events aren't guaranteed to arrive in the order the votes were cast. Use the time of the vote included in each event if order matters to your system.
Each batch is sent only once. If your endpoint is unavailable, responds too slowly or returns an error when a batch is sent, Simply Voting doesn't try again, and the vote events in that batch won't be delivered. Webhooks stay active, and later batches are still sent. If your system needs a complete record of who voted, compare it against the reports available in the Election Manager.
About the API documentation
The Webhooks API documentation is intended for the developers who build and maintain your endpoint. You can also open it from the Webhooks documentation link on the Integrations page. It covers:
The format of the requests and vote events, with an example.
Timing and delivery expectations.
The details on the test requests.
How to verify each request using the signing secret and the request headers.
A changelog of the webhook format.