Webhooks

With webhooks, Vereinsantrag notifies your own systems automatically and in real time whenever certain events happen in your club – for example when a new application arrives or is accepted. This lets you forward applications to a CRM, an accounting system or an automation tool without any manual steps.

Technically, Vereinsantrag sends an HTTP POST request containing the event data to an address you configure (the "target URL").

Note: The app's user interface is in German; German labels are given in quotes where they help you locate an element.

Note: Webhooks are available from the Gold tier.

Security: verifying the signature

Delivery and retries

Target URL requirements

FAQ

Setting up a webhook

Open the club settings and switch to the Webhooks tab.

Click New webhook ("Neuer Webhook").

Fill in the fields:

Name – a free-text name for recognition, e.g. "CRM integration".

Target URL ("Ziel-URL") – the https address the data is sent to.

Events – select one or more events you want to be notified about.

Active ("Aktiv") – only active webhooks receive messages.

After saving, the secret is shown once.

⚠️ Important: The secret is shown in plain text only this one time. Copy it and store it securely – it is needed to verify the signature (see Verifying the signature). If you lose it, you can generate a new one at any time.

Available events

Shown in the app	Value in the message	Triggered when …
"Antrag eingegangen"	`ApplicationReceived`	a new application (membership, change or cancellation) is received
"E-Mail (DOI) bestätigt"	`EmailConfirmed`	the applicant has confirmed their e-mail address
"Antrag akzeptiert"	`ApplicationAccepted`	an application was accepted
"Antrag abgelehnt"	`ApplicationRejected`	an application was rejected

A webhook only receives the events you have assigned to it.

Managing webhooks

In the overview, each webhook has a menu (⋮) with the following actions:

History ("Verlauf") – shows the most recent deliveries with status, HTTP response code, duration and any error message.

Test ("Testen") – sends a sample message to the target URL to check the connection.

Rotate secret ("Secret neu erzeugen") – creates a new secret. The previous one becomes invalid immediately, so your integration must be switched to the new secret afterwards.

Edit ("Bearbeiten") – change name, URL, events and the active state. The secret stays unchanged.

Delete ("Löschen") – removes the webhook together with its delivery history.

💡 The dashboard additionally offers a "Webhook-Zustellungen" (webhook deliveries) tile. It shows successful and failed deliveries over time – either across all webhooks or per webhook.

Message structure

Every message is a POST request with a JSON body and several headers.

Headers

Header	Meaning
`X-Vereinsantrag-Event`	The event type, e.g. `ApplicationReceived`.
`X-Vereinsantrag-Delivery`	Unique ID of this delivery – ideal for detecting retries.
`X-Vereinsantrag-Timestamp`	Time the signature was created, as a Unix timestamp (seconds).
`X-Vereinsantrag-Signature`	Signature of the message in the form `sha256=<hex>` (see below).

Body (example)

{
  "event": "ApplicationReceived",
  "occurredAt": "2026-06-26T08:30:00Z",
  "clubId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "submission": {
    "id": "9b2c7d10-1f4e-4a2b-8c33-0a1b2c3d4e5f",
    "type": "SubmitMemberships",
    "state": "New",
    "firstname": "Max",
    "lastname": "Mustermann",
    "email": "max@example.com",
    "dateCreate": "2026-06-26T08:29:55Z",
    "confirmDate": null
  }
}

Fields in the submission object:

type – kind of application: SubmitMemberships (membership), SubmitChanges (change) or SubmitCancellations (cancellation).

state – current status: New (submitted), NewNotConfirmed (submitted, e-mail not yet confirmed), Proceeded (accepted and processed) or Rejected (rejected).

confirmDate – time the e-mail address was confirmed, or null if not (yet) confirmed.

Security: verifying the signature

Every message is signed with your secret using HMAC-SHA256. This lets you confirm that the message really comes from Vereinsantrag and was not altered in transit. Verify the signature before processing the data.

This is how the signature is built (and how you verify it):

Read the X-Vereinsantrag-Timestamp header (timestamp) and X-Vereinsantrag-Signature.

Build the string "<timestamp>.<raw-body>" – i.e. the timestamp, a dot, then the unmodified JSON body you received.

Compute its HMAC-SHA256 using your secret as the key and prepend sha256=.

Compare the result with the value from X-Vereinsantrag-Signature (use a constant-time comparison).

Always use the raw, unmodified body. If the JSON is parsed and re-serialized, the signature changes.

Example (Node.js / Express)

Optional but recommended: reject messages whose X-Vereinsantrag-Timestamp is too far in the past (e.g. older than 5 minutes) to prevent replaying old messages.

Delivery and retries

Your endpoint should respond quickly with a status code in the 2xx range. Only then is the delivery considered successful.

If the endpoint does not respond with 2xx, is unreachable or too slow, Vereinsantrag retries the delivery up to three times. After that it is marked as failed.

Because of these retries, the same message may arrive more than once. Make your processing idempotent and use the X-Vereinsantrag-Delivery ID to recognize messages you have already handled.

Handle expensive work asynchronously where possible: respond with 200 OK first, then continue in the background.

You can review the outcome of every delivery at any time under History ("Verlauf").

Target URL requirements

Must start with https://.

Must be publicly reachable from the internet. Internal or local addresses (e.g. localhost, 127.0.0.1 or addresses from private networks) are rejected for security reasons.

Should only accept requests with a valid signature.

FAQ

I can't edit the Webhooks tab / the controls are greyed out.
Webhooks are available from the Gold tier.

Saving shows "The URL points to a disallowed (internal) address" or similar.
The target URL must use https and be publicly reachable – see Target URL requirements. For local testing, use a tunnel service that provides a public https address.

I lost my secret.
Use Rotate secret ("Secret neu erzeugen") to create a new one and store it in your integration. The old secret becomes invalid immediately.

A delivery shows "Failed" in the history.
Check the HTTP response code or error message shown there. Common causes: your endpoint does not respond with 2xx, is unreachable, or responds too slowly. Use Test ("Testen") to check the connection directly.

Can the same webhook receive multiple events?
Yes. Just select several events when creating or editing it. Which event triggered a given message is shown in the X-Vereinsantrag-Event header and in the event field.

Contents#

Setting up a webhook#

Available events#

Managing webhooks#

Message structure#

Headers#

Body (example)#

Security: verifying the signature#

Example (Node.js / Express)#

Delivery and retries#

Target URL requirements#

FAQ#

Contents

Setting up a webhook

Available events

Managing webhooks

Message structure

Headers

Body (example)

Security: verifying the signature

Example (Node.js / Express)

Delivery and retries

Target URL requirements

FAQ