DocumentationTutorials, scenarios & features

Discover our expansive knowledgebase and learn how to get the most out of Citizen Ticket.

Tutorials

Scenarios

Features

Receive notifications at your webhook endpoint

Receive notifications at an HTTPS webhook endpoint in your own application. After you register a webhook endpoint, the Citizen Ticket platform can push real-time data to your application when customers complete payments.

Get started

First you must prepare your own web application:

  1. Create a webhook endpoint handler that is able to receive JSON payloads via POST requests,
  2. Ensure your endpoint can be accessed via a publically accessible URL. Your server must support HTTPS and have a valid certificate,

Set up your webhook

  1. Sign in to your organiser account
  2. Go to Organiser Profile
  3. Select “Webhooks”
  4. Click “+ Add Webhook”
  5. Enter the Fully Qualified URL for your application’s webhook endpoint
  6. Click “Save”
  7. A unique “Signing Secret” will be generated. Keep this secret and secure. You can use the buttons to reveal it and/or copy it directly to your clipboard. Your application should use this to verify webhook notifications (see “Secure your endpoint” below)

Test your webhook

  1. Sign in to your organiser account
  2. Go to Organiser Profile
  3. Select “Webhooks”
  4. Next to a webhook, press the “Test” button to issue an immediate test event. A popup notification displays whether it is successful,
  5. The status of the request can also be viewed by pressing “History”. This screen shows a list of historic notifications along with delivery statuses.

Secure your endpoint

Your endpoint handler should:

  1. Return a 2XX HTTP status code to indicate success. Any other response code is considered a failure and will be retried,
  2. Return quickly - If it takes longer than a couple of seconds, it is considered a failure and will be retried. If you need longer than this, queue the notification and process it asynchronously.
  3. Store the shared Signing Secret securely - Do not commit it into version control. Restrict read access to it.
  4. Verify the cryptographic signature:
    1. Calculate your own signature from the body of the request given to you plus your secret knowledge of the Signing Secret as follows: Signature=base64(HMAC-SHA256(body, SigningSecret)) 
    2. Verify it matches the value passed to you in the X-Signature header
    3. If it does not match, discard the message. This implies the message body has been altered en-route by a third party. This may be an indication of a man-in-the-middle attack.
  1. Verify the timestamp given in the JSON body. We recommend you discard messages older than 5 minutes.
  2. Verify the id given in the JSON body. We recommend you keep track of recent UUIDs and discard duplicates to guard against replay attacks.

Replay webhook notifications

  1. Sign in to your organiser account
  2. Go to Organiser Profile
  3. Select “Webhooks”
  4. Next to a webhook, press the “History” button to open the history screen,
  5. Next to a historic notification, press the “Replay” button to repeat it.

Supported notifications

These are the webhook event types currently supported by the platform:

event_type

Trigger

Payload

test

Triggers when an organiser presses “Test” in the admin UI.

A hard-coded message.

payment.complete

Triggers when a customer completes a payment.

For customers on a payment plan, this event triggers both for initial payment as well as each later installment.

Fields identifying the customer and the ticket(s) being purchased.

The ticket platform that saves you time and makes you money.


Pricing Book a demo
About Us
Customer Helpdesk
Legal
Subscribe
  • Be in the know about events, offers and freebies.
  • Follow

How we use cookies

cookie icon

Hello! We would like to use cookies on this site to:

  • Store your session and log in details
  • Better understand our web traffic (analytics)
  • Provide social media and advertising features

Please read our cookie policy.