The Mobilitybox
  • Login
GENERAL
  • Welcome
  • UPDATED API Changelog
  • Authentication
MOBILITYBOX CONNECT
  • Overview
  • NEW Connect API
    • API Documentation
PUBLIC TRANSIT TICKETING
  • Ticketing API
    • API Documentation
    • Tutorial
    • NEW Idempotent Requests
    • Invoicing
    • Subscriptions
    • Restore Tickets
    • Manage Tariff Settings
  • App Integration
  • Deutschlandticket
  • Price Change Deutschlandticket
  • Apple & Google Wallet
  • Data Storage Strategy
  • Ticketing Components
    • Fastlink
    • Fastlink API
    • Webhook (Fastlink)
    • Mobility Wallet
PUBLIC TRANSIT DATA
  • Quickstart
  • API Documentation
  • Sessions
  • Examples

Webhook (Fastlink only)

Our webhook system lets you stay informed about real-time essential events in your Fastlink shop.

Whether it's the successful completion of an order or changes in payment status, our system ensures that you are always up-to-date.

On this Page
  • Overview
  • Setup
    • Certificate Pinning
  • Events
    • Default Structure
    • Payment Succeeded
    • Payment Failed
    • Order Performed
    • Coupon Created
    • Coupon Activated
    • Subscription Reordered
    • Coupon Restored

Overview

The Webhook system lets you receive real-time notifications when important events occur in your Fastlink shop. The Messages contain all the relevant information about the event they refer to and are sent over HTTPS as JSON payloads. You can use these notifications to automate your backend systems and trigger actions when a specific event occurs.

Setup

Requirements

You must have an active Mobilitybox account and a Fastlink shop set up.

Step 1 - Create your Webhook

Go to https://webhook-fastlink.themobilitybox.com/hooks and Login.

Click on "Create Webhook"

Step 2 - Select your Referrer

Please provide a name and specify your referrer shop.

Click then "Create hook" to save your Webhook.

Step 3 - Configure your Endpoint URL

Now click "Configure" on your created Webhook, and select "Push to URL".

Type in your Endpoint URL and save your changes with "Update Hook"

Your endpoint should respond to every message with a 200 or 201 status code.

Step 4 - Test your Webhook

Click on "Send a Test Message" to receive a message on your Endpoint.

Make sure that it has been received successfully.

Certificate Pinning

Certificate pinning is a security mechanism in which the server's certificate is saved to ensure the connection is only established to your server endpoint and prevent attacks through fake certificates.

Step 1 - Select Certificate Pinning

Click on your Webhook and configure.

Now select Certificate Pinning and click on the activate checkbox.

Step 2 - Enter your Certificate Serial number

Please enter the serial number from your certificate.

You can locate it by visiting your website and clicking on the lock icon in your browser.

Step 3 - Step 3 - Enter your Certificate Fingerprint

Please enter the SHA 256 Fingerprint from your certificate.

You can locate it using the same method as before.

Now save your changes with "Update Hook"!

Events

Default structure
  • Attributes
  • event_type

    The type of event triggered

    Valid event types:

    • fastlink.payment.succeeded
    • fastlink.payment.failed
    • mobilitybox.order.performed
    • mobilitybox.coupon.created
    • mobilitybox.coupon.activated
    • mobilitybox.subscription.reordered
    • mobilitybox.coupon.restored

  • event_details

    JSON Object with specific attributes

  • version

    The version of the webhook service

  • meta_data
    • sequence_number

      The sequence number of the request

    • attempt_counter

      The number of attempts made to send the webhook request

    • message_created_at

      The timestamp when the webhook request was created

    • request_sent_at

      The timestamp when the webhook request was sent

Response
{
  "event_type": "{webhook-service}.{event}",
  "event_details": {},
  "version": "3.0",
  "meta_data": {
    "sequence_number": 123,
    "attempt_counter": 1,
    "message_created_at": "2023-04-14T12:00:00.000Z",
    "request_sent_at": "2023-04-14T12:00:00.000Z"
  }
}
          
Payment succeeded
  • Attributes
  • event_type

    fastlink.payment.succeeded

  • event_details
    • order_id

      Mobilitybox order ID.

    • subscription_id

      The Mobilitybox subscription ID.

    • coupon_id

      The Mobilitybox coupon ID.

    • fastlink_referrer_code

      The referrer code from your Fastlink shop.

    • fastlink_order_reference

      The given Fastlink order reference.

    • is_subscription

      A boolean value indicating whether this is a subscription order.

    • payment_type

      Defines which type of payment it is. Valid types: checkout, recurring_payment.

    • payed_at

      The ISO-8601 timestamp when the payment was done.

    • ordered_subscription_cycle optional hash

      Information About the subscription cycle that was paid/ordered.

      • id

        Mobilitybox subscription cycle ID.

      • valid_from

        Mobilitybox subscription cycle ID.

      • valid_until

        Mobilitybox subscription cycle ID.

      • ordered

        Has the value true if this subscription cycle was paid/ordered.

      • coupon_activated

        Has the value true if the coupon was activated/reactivated for this subscription cycle and the ticket was generated.

    • next_unordered_subscription_cycle optional hash

      Information About the next unordered subscription cycle.

      • id

        Mobilitybox subscription cycle ID.

      • valid_from

        Mobilitybox subscription cycle ID.

      • valid_until

        Mobilitybox subscription cycle ID.

      • ordered

        Has the value true if this subscription cycle was paid/ordered.

      • coupon_activated

        Has the value true if the coupon was activated/reactivated for this subscription cycle and the ticket was generated.

Response
{
  "event_type": "fastlink.payment.succeeded"
  "event_details": {
    "order_id": "mobilitybox-order-uuid",
    "subscription_id": "mobilitybox-subscription-uuid",
    "coupon_id": "mobilitybox-coupon-uuid",
    "fastlink_referrer_code": "TEST-REF123",
    "fastlink_order_reference": "optional string",
    "is_subscription": true,
    "price_in_cents": 4900,
    "payment_type": "checkout",
    "payed_at": "2023-05-05T12:30:00+02:00"
  }
}
          
Payment failed
  • Attributes
  • event_type

    fastlink.payment.failed

  • event_details
    • order_id

      Mobilitybox order ID.

    • subscription_id

      The Mobilitybox subscription ID.

    • coupon_id

      The Mobilitybox coupon ID.

    • fastlink_referrer_code

      The referrer code from your Fastlink shop.

    • fastlink_order_reference

      The given Fastlink order reference.

    • is_subscription

      A boolean value indicating whether this is a subscription order.

    • payment_type

      Defines which type of payment it is. Valid types: checkout, recurring_payment.

    • payed_at

      The ISO-8601 timestamp when the payment was done.

    • ordered_subscription_cycle optional hash

      Information About the subscription cycle that was paid/ordered.

      • id

        Mobilitybox subscription cycle ID.

      • valid_from

        Mobilitybox subscription cycle ID.

      • valid_until

        Mobilitybox subscription cycle ID.

      • ordered

        Has the value true if this subscription cycle was paid/ordered.

      • coupon_activated

        Has the value true if the coupon was activated/reactivated for this subscription cycle and the ticket was generated.

    • next_unordered_subscription_cycle optional hash

      Information About the next unordered subscription cycle.

      • id

        Mobilitybox subscription cycle ID.

      • valid_from

        Mobilitybox subscription cycle ID.

      • valid_until

        Mobilitybox subscription cycle ID.

      • ordered

        Has the value true if this subscription cycle was paid/ordered.

      • coupon_activated

        Has the value true if the coupon was activated/reactivated for this subscription cycle and the ticket was generated.

Response
{
  "event_type": "fastlink.payment.failed"
  "event_details": {
    "order_id": "mobilitybox-order-uuid",
    "subscription_id": "mobilitybox-subscription-uuid",
    "coupon_id": "mobilitybox-coupon-uuid",
    "fastlink_referrer_code": "TEST-REF123",
    "fastlink_order_reference": "optional string",
    "is_subscription": true,
    "price_in_cents": 4900,
    "payment_type": "recurring_payment",
    "payed_at": "2023-05-05T12:30:00+02:00"
  }
}
          
Order performed
  • Attributes
  • event_type

    mobilitybox.order.performed

  • event_details
    • order_id

      Mobilitybox order ID.

    • fastlink_order_reference

      The given Fastlink order reference.

    • fastlink_referrer_code

      The referrer code from your Fastlink shop.

    • restore_secret

      The Mobilitybox Restore Secret for this Order.

Response
{
  "event_type": "mobilitybox.order.performed"
  "event_details": {
    "order_id": "mobilitybox-order-uuid",
    "fastlink_order_reference": "",
    "fastlink_referrer_code": "TEST-123abc",
    "restore_secret": "mobilitybox-restore-secret-uuid"
  }
}
          
Coupon created
  • Attributes
  • event_type

    mobilitybox.coupon.created

  • event_details
    • order_id

      Mobilitybox order ID.

    • fastlink_order_reference

      The given Fastlink order reference.

    • fastlink_referrer_code

      The referrer code from your Fastlink shop.

    • coupon_id

      The Mobilitybox coupon ID.

    • product_id

      The Mobilitybox product ID.

    • is_subscription

      A boolean value indicating whether this is a subscription order.

    • subscription_id

      The Mobilitybox subscription ID.

Response
{
  "event_type": "mobilitybox.coupon.created"
  "event_details": {
    "order_id": "mobilitybox-order-uuid",
    "fastlink_order_reference": "",
    "fastlink_referrer_code": "TEST-123abc",
    "coupon_id": "mobilitybox-coupon-uuid",
    "product_id": "mobilitybox-product-uuid",
    "is_subscription": true,
    "subscription_id": "mobilitybox-subscription-uuid"
  }
}
          
Coupon activated
  • Attributes
  • event_type

    mobilitybox.coupon.activated

  • event_details
    • order_id

      Mobilitybox order ID.

    • fastlink_order_reference

      The given Fastlink order reference.

    • coupon_id

      The Mobilitybox coupon ID.

    • subscription_id

      The Mobilitybox subscription ID.

    • ticket_id

      The Mobilitybox ticket ID.

    • subscription_cycle_id

      The Mobilitybox subscription cycle ID.

    • is_restored

      Has the value true if this coupon was restored

Response
{
  "event_type": "mobilitybox.coupon.activated"
  "event_details": {
    "order_id": "mobilitybox-order-uuid",
    "fastlink_order_reference": "",
    "coupon_id": "mobilitybox-coupon-uuid",
    "subscription_id": "mobilitybox-subscription-uuid",
    "ticket_id": "mobilitybox-ticket-uuid",
    "subscription_cycle_id": "mobilitybox-cycle-uuid",
    "is_restored": false
  }
}
          
Subscription reordered
  • Attributes
  • event_type

    mobilitybox.subscription.reordered

  • event_details
    • order_id

      Mobilitybox order ID.

    • fastlink_order_reference

      The given Fastlink order reference.

    • fastlink_referrer_code

      The referrer code from your Fastlink shop.

    • coupon_id

      The Mobilitybox coupon ID.

    • product_id

      The Mobilitybox product ID.

    • is_subscription

      A boolean value indicating whether this is a subscription order.

    • subscription_id

      The Mobilitybox subscription ID.

Response
{
  "event_type": "mobilitybox.subscription.reordered"
  "event_details": {
    "order_id": "mobilitybox-order-uuid",
    "fastlink_order_reference": "",
    "fastlink_referrer_code": "TEST-123abc",
    "coupon_id": "mobilitybox-coupon-uuid",
    "product_id": "mobilitybox-product-uuid",
    "is_subscription": true,
    "subscription_id": "mobilitybox-subscription-uuid"
  }
}
          
Coupon restored
  • Attributes
  • event_type

    mobilitybox.coupon.restored

  • event_details
    • order_id

      Mobilitybox order ID.

    • fastlink_order_reference

      The given Fastlink order reference.

    • fastlink_referrer_code

      The referrer code from your Fastlink shop.

    • coupon_id

      The Mobilitybox coupon ID.

    • original_coupon_id

      The original Mobilitybox coupon ID.

    • is_subscription

      A boolean value indicating whether this is a subscription order.

    • subscription_id

      The Mobilitybox subscription ID.

    • original_subscription_id

      The original Mobilitybox subscription ID.

Response
{
  "event_type": "mobilitybox.coupon.restored"
  "event_details": {
    "order_id": "mobilitybox-order-uuid",
    "fastlink_order_reference": "",
    "fastlink_referrer_code": "TEST-123abc",
    "coupon_id": "mobilitybox-coupon-uuid",
    "original_coupon_id": "mobilitybox-coupon-uuid",
    "is_subscription": true,
    "subscription_id": "mobilitybox-subscription-uuid",
    "original_subscription_id": "mobilitybox-coupon-uuid"
  }
}
          

Mobilitybox is a service run by Vesputi GmbH | Privacy Policy