API und Webhooks
Lassen Sie andere Programme die Inhalte, Formulareinsendungen und Abonnenten Ihrer Website lesen, und benachrichtigen Sie sie, sobald etwas geschieht.
Wenn Ihr Plan es enthält, verbindet Entwickler Ihre Website mit anderen Werkzeugen — einem Automatisierungsdienst, einer App, Ihrem eigenen Code. Der Bereich hat zwei Hälften: API-Schlüssel für ein Programm, das von der Website lesen will, und Webhooks für eines, das benachrichtigt werden will, wenn etwas geschieht. Nur Administratoren und Inhaber sehen ihn.
API-Schlüssel
Klicken Sie auf Neuer API-Schlüssel, benennen Sie ihn nach dem, was ihn verwenden wird, und kreuzen Sie nur an, was er lesen muss. Der Schlüssel wird einmal angezeigt — kopieren Sie ihn sofort. Geht er verloren, widerrufen Sie ihn und erstellen einen neuen; ein widerrufener Schlüssel funktioniert sofort nicht mehr.
| Darf lesen | Das heißt |
|---|---|
| Beiträge, Seiten, Partituren und Veröffentlichungen | Was die öffentliche Website zeigt. Texte und Dateien nur für Mitglieder bleiben außen vor. |
| Formulareinsendungen | Was Besucher gesendet haben — Namen, E-Mail-Adressen, Antworten. |
| Newsletter-Abonnenten | E-Mail-Adressen und Namen der Abonnenten. |
Die API aufrufen
Senden Sie den Schlüssel im Header Authorization: Bearer vp_…. Der Bereich Entwickler zeigt die API-Adresse Ihrer Website und jeden Endpunkt zum Kopieren:
| Endpunkt | Liefert |
|---|---|
/posts | Veröffentlichte Beiträge, die neuesten zuerst, ohne ihren Text. |
/posts/{slug} | Einen Beitrag mit seinem Text. |
/pages | Veröffentlichte Seiten mit ihrem Text. |
/scores | Veröffentlichte Partituren in der Reihenfolge der Website, mit ihren Werkangaben. |
/scores/{slug} | Eine Partitur mit Sätzen, Uraufführung und Dateien. |
/releases | Veröffentlichte Aufnahmen mit ihren Covern. |
/releases/{slug} | Eine Veröffentlichung mit ihren Titeln und Plattform-Links. |
/forms/{formId}/submissions | Die Einsendungen eines Formulars, die neuesten zuerst. |
/subscribers | Bestätigte Newsletter-Abonnenten. |
- Listen kommen seitenweise:
?page=2für die nächste Seite,?per_page=für bis zu 100 auf einmal. Jede Antwort nennt die Gesamtzahl. - Auf einer mehrsprachigen Website liefert
?locale=de(oder eine andere Sprache) die Inhalte dieser Sprache. - Die ID eines Formulars ist der letzte Teil der Adresse, wenn Sie es unter Formulare öffnen.
- Beträge stehen in der kleinsten Einheit der Währung:
1250bedeutet 12,50.
Webhooks
Klicken Sie auf Neuer Webhook, geben Sie eine https-Adresse ein, die POST-Anfragen annimmt, und wählen Sie die Ereignisse, die gesendet werden sollen. Tritt eines ein, sendet VPress es als JSON dorthin.
| Ereignis | Gesendet, wenn |
|---|---|
post.published | Ein Beitrag erscheint — als veröffentlicht gespeichert oder nach Plan. |
form.submitted | Ein Besucher eines der Formulare der Website sendet. |
newsletter.subscribed | Jemand sein Newsletter-Abonnement bestätigt. |
order.paid | Eine Shop-Bestellung bezahlt wird. |
score.published | Eine Partitur wird unter /scores aufgeführt. |
release.published | Eine Veröffentlichung wird unter /music aufgeführt. |
Test senden schickt sofort einen Ping, damit Sie sehen, ob Ihr Endpunkt antwortet, und Letzte Zustellungen unter jedem Webhook zeigt, was gesendet wurde und was zurückkam. Eine Zustellung ohne 2xx-Antwort wird im Lauf des folgenden Tages erneut versucht. Nach 20 Fehlschlägen in Folge schaltet sich der Webhook ab; reparieren Sie Ihren Endpunkt und speichern Sie den Webhook, um ihn wieder einzuschalten.
Prüfen, ob eine Zustellung echt ist
Beim Anlegen eines Webhooks wird Ihnen sein Signaturgeheimnis einmal angezeigt. Jede Zustellung trägt einen Header X-VPress-Signature der Form t=…,v1=…: t ist der Sendezeitpunkt, v1 ein HMAC-SHA256 aus Zeitpunkt, einem Punkt und dem unveränderten Body, mit diesem Geheimnis als Schlüssel. Berechnen Sie ihn selbst, vergleichen Sie, und weisen Sie Zustellungen zurück, die älter als fünf Minuten sind. Es ist dasselbe Verfahren wie bei Stripe, daher können die meisten Webhook-Bibliotheken es prüfen.
Brauchen Sie noch Hilfe?
Wenn die Artikel Ihre Frage nicht beantworten, eröffnen Sie ein Ticket, und das VPress-Team meldet sich bei Ihnen.