API and webhooks
Let other programs read your site's content, form submissions and subscribers, and tell them the moment something happens.
If your plan includes it, Developers connects your website to other tools — an automation service, a mobile app, your own code. It has two halves: API keys, for a program that wants to read from the site, and Webhooks, for one that wants to be told when something happens. Only admins and owners see it.
API keys
Press New API key, name it after what will use it, and tick only what it needs to read. The key is shown once — copy it then. If it's lost, Revoke it and make another; a revoked key stops working at once.
| It may read | Which means |
|---|---|
| Posts, pages, scores and releases | What the public site shows. Members-only text and files are left out. |
| Form submissions | What visitors sent — names, emails, answers. |
| Newsletter subscribers | Subscribers' email addresses and names. |
Calling the API
Send the key in an Authorization: Bearer vp_… header. The Developers screen shows your site's API address and every endpoint, ready to copy:
| Endpoint | Returns |
|---|---|
/posts | Published posts, newest first, without their text. |
/posts/{slug} | One post, with its text. |
/pages | Published pages, with their text. |
/scores | Published scores in the site's order, with their catalogue facts. |
/scores/{slug} | One score, with its movements, first performance and files. |
/releases | Published releases, with their covers. |
/releases/{slug} | One release, with its tracks and platform links. |
/forms/{formId}/submissions | One form's submissions, newest first. |
/subscribers | Confirmed newsletter subscribers. |
- Lists come a page at a time: add
?page=2for the next, and?per_page=for up to 100 at once. Each answer says how many there are in total. - On a site in several languages, add
?locale=de(or another language) for that language's content. - A form's ID is the last part of the address when you open it under Forms.
- Amounts are in the smallest unit of the currency:
1250is 12.50.
Webhooks
Press New webhook, enter an https address that accepts POST requests, and choose the events to send. When one happens, VPress sends it there as JSON.
| Event | Sent when |
|---|---|
post.published | A post goes live — saved as published, or by its schedule. |
form.submitted | A visitor sends one of the site's forms. |
newsletter.subscribed | Someone confirms their newsletter subscription. |
order.paid | A shop order is paid. |
score.published | A score is listed at /scores. |
release.published | A release is listed at /music. |
Send test sends a ping straight away so you can see your endpoint answer, and Recent deliveries under each webhook shows what was sent and what came back. A delivery that doesn't get a 2xx answer is tried again over the following day. After 20 failures in a row the webhook switches itself off; fix your endpoint, then save the webhook to switch it back on.
Checking a delivery is genuine
When you create a webhook you're shown its signing secret, once. Every delivery carries an X-VPress-Signature header of the form t=…,v1=…: t is the time it was sent, and v1 is an HMAC-SHA256 of the time, a dot and the raw body, keyed with that secret. Compute it yourself and compare, and reject deliveries more than five minutes old. It's the same scheme Stripe uses, so most webhook libraries can check it.
Still need help?
If the articles don't answer your question, open a ticket and the VPress team will get back to you.