Skip to main content

​
Introduction

A webhook is an HTTP request triggered by an event in a source system and sent to a destination system, with a payload of data. In the Tyk Developer Portal, webhooks allow you to subscribe to specific events and receive real-time notifications when those events occur. This enables you to integrate the Developer Portal with external systems and automate workflows based on portal events.

​
Use Cases

  • Slack Notifications: Send a notification to a Slack channel when a new user registers.
  • CRM Data Synchronization: Keep your CRM system up-to-date with the latest user and application data from the Tyk Developer Portal.

​
Supported Portal Events

The portal fires the following webhook events: The complete list of events and their corresponding payloads is outlined below.

​
Register Invite

This event is fired whenever a user is invited to register in the portal via the admin UI or APIs.

​
New User Registered

This event is fired whenever a new user is created via APIs, the admin UI, and the live portal UI (SSO or invite though the org dashboard or self-registration or invite code). Sample payload:
Expandable
{
    "Event": "UserRegistered",
    "Message": {
        "ID": 29,
        "Email": "developer@user.com",
        "First": "FirstName",
        "Last": "Lastname",
        "OrgID": 1,
        "Provider": "password",
        "Status": "active",
        "CreatedAt": "2024-04-22T16:38:54.068565+02:00",
        "ByUser": 1,
        "CustomAttributes": [
            {
                "Identifier": "company-name",
                "Value": "ACME"
            }
        ]
    },
    "Timestamp": "2024-04-22T16:38:54.082037+02:00"
}

​
User Account Activated

This event is fired whenever a user (either an admin or a developer) account is activated via APIs or the admin UI. Sample payload:
Expandable
{
    "Event": "UserAccountActivated",
    "Message": {
        "ID": 7,
        "Email": "devD1@tyk.io",
        "First": "Test",
        "Last": "User",
        "OrgID": 7,
        "Provider": "password",
        "Status": "active",
        "CreatedAt": "2024-04-22T15:46:40.128398Z",
        "ByUser": 1,
        "CustomAttributes": [
            {
                "Identifier": "boolean-custom-attribute",
                "Value": "false"
            }
        ]
    },
    "Timestamp": "2024-04-22T17:52:22.673077+02:00"
}

​
User Account Deactivated

This event is fired whenever a user account is deactivated via APIs or the admin UI. Sample payload:
Expandable
{
  "Event": "UserAccountDeactivated",
  "Message": {
    "ID": 7,
    "Email": "test@user.io",
    "First": "Test",
    "Last": "User",
    "OrgID": 7,
    "Provider": "password",
    "Status": "inactive",
    "CreatedAt": "2024-04-22T15:46:40.128398Z",
    "ByUser": 1,
    "CustomAttributes": [
      {
        "Identifier": "boolean-custom-attribute",
        "Value": "false"
      }
    ]
  },
  "Timestamp": "2024-04-22T17:51:22.24066+02:00"
}

​
Password Reset

This event is fired whenever a user tries to reset their password. Sample payload:
Expandable
{
    "Event": "PasswordReset",
    "Message": {
        "ID": 7,
        "Email": "test@user.io",
        "First": "Test",
        "Last": "User",
        "OrgID": 7,
        "Provider": "password",
        "Status": "active",
        "CreatedAt": "2024-04-22T15:46:40.128398Z",
        "CustomAttributes": [
            {
                "Identifier": "boolean-custom-attribute",
                "Value": "false"
            }
        ]
    },
    "Timestamp": "2024-04-22T17:58:10.223162+02:00"
}

​
New Application Registered

This event is fired whenever a new app is created via APIs, and the live portal UI (either via the checkout or the create app button in the developer’s dashboard). Sample payload:
Expandable
{
    "Event": "ApplicationRegistered",
    "Message": {
        "ID": 1,
        "Name": "New App",
        "UserID": 1,
        "CreatedAt": "2024-04-18T13:29:23.738726+02:00"
    },
    "Timestamp": "2024-04-18T13:29:23.744826+02:00"
}

​
New Credential Is Created

This event is fired whenever a new credential is created via APIs, the admin UI (creation after approval) and the live portal UI. Sample payload:
Expandable
{
    "Event": "CredentialRegistered",
    "Message": {
        "ID": 1,
        "ByUser": 3,
        "AccessRequestID": 1,
        "AppID": 3,
        "CreatedAt": "2024-04-18T13:48:08.489611+02:00"
    },
    "Timestamp": "2024-04-18T13:48:08.494266+02:00"
}

​
New Access Request Created

This event is fired whenever a new access request is created via APIs and the live portal UI. Sample payload:
Expandable
{
    "Event": "AccessRequestCreated",
    "Message": {
        "ID": 0,
        "AppID": 1,
        "ByUser": 2,
        "Status": "approved",
        "ProductIDs": [
            1
        ],
        "PlanID": 2,
        "CreatedAt": "0001-01-01T00:00:00Z"
    },
    "Timestamp": "2024-04-22T18:09:45.245357+02:00"
}

​
An Access Request Is Approved

This event is fired whenever an access request is approved or auto-approved via the admin APIs or admin UI. Sample payload:
Expandable
{
    "Event": "AccessRequestApproved",
    "Message": {
        "ID": 1,
        "AppID": 3,
        "ByUser": 3,
        "Status": "approved",
        "ProductIDs": [
            1
        ],
        "PlanID": 2,
        "CreatedAt": "2024-04-18T13:36:02.769109+02:00"
    },
    "Timestamp": "2024-04-18T13:48:08.508925+02:00"
}

​
An Access Request Is Rejected

This event is fired whenever an access request is rejected via the admin APIs or the admin UI. Sample payload:
Expandable
{
    "Event": "AccessRequestRejected",
    "Message": {
        "ID": 6,
        "AppID": 7,
        "ByUser": 3,
        "Status": "rejected",
        "ProductIDs": [],
        "PlanID": 2,
        "CreatedAt": "2024-04-18T14:40:15.81038+02:00"
    },
    "Timestamp": "2024-04-18T14:40:28.998297+02:00"
}

​
New Organization Registered

This event is fired whenever a new consumer organization is created via the admin APIs, the live portal (the become an organization flow) or the admin UI. Sample payload:
Expandable
{
    "Event": "OrganisationRegistered",
    "Message": {
        "ID": 8,
        "Name": "Organisation added from Admin UI",
        "CreatedAt": "2024-04-18T16:12:09.8437+02:00"
    },
    "Timestamp": "2024-04-18T16:12:09.849045+02:00"
}

​
New Organization Registration Request Created

This event is fired whenever a new organization request is created via the live portal (the become an organization flow) or the admin UI. Sample payload:
Expandable
{
    "Event": "OrganisationRequestCreated",
    "Message": {
        "Name": "Organisation added from Live Portal (the become an org flow)",
        "AdminEmail": "dev@tyk.io",
        "AdminID": 3,
        "ByUser": 3,
        "TeamIDs": [],
        "Status": "pending",
        "CreatedAt": "2024-04-18T16:13:50.766139+02:00"
    },
    "Timestamp": "2024-04-18T16:13:50.796234+02:00"
}

​
Organization Registration Request Is Approved

This event is fired whenever an organization registration request is approved by an admin user. Sample payload:
Expandable
{
  "Event": "OrganisationRequestApproved",
  "Message": {
    "ID": 11,
    "Email": "dev@tyk.io",
    "First": "Developer",
    "Last": "User",
    "OrgID": 2,
    "Provider": "password",
    "Status": "inactive",
    "CreatedAt": "2024-04-24T15:26:04.312618088Z",
    "CustomAttributes": []
  },
  "Timestamp": "2024-04-24T15:26:04.329072196Z"
}

​
Organization Request Is Rejected

This event is fired whenever a new organization request is rejected by an admin user. Sample payload:
Expandable
{
    "Event": "OrganisationRequestRejected",
    "Message": {
        "Name": "ACME",
        "AdminEmail": "dev@tyk.io",
        "AdminID": 17,
        "ByUser": 17,
        "TeamIDs": [],
        "Status": "rejected",
        "CreatedAt": "2024-04-18T16:27:34.012613+02:00"
    },
    "Timestamp": "2024-04-18T16:27:50.504654+02:00"
}

​
Configuration

In the Tyk Developer Portal, webhooks can be configured using the Developer Portal API or the UI. The configuration includes setting up the
  1. Target endpoint
  2. Selecting the events to subscribe to
Follow this tutorial to learn how to create and configure a webhook in the Developer Portal.

​
Payload Structure

The payload of a webhook is a JSON object with the following structure: 
{
  "Event": "UserRegistered",
  "Message": {
    // Message object structure varies depending on the event
  },
  "Timestamp": "2026-02-26T06:33:00.000Z"
}
​
Event
The name of the event that triggered the webhook. Check the supported events section below for the list of available events.
​
Message
A JSON object containing the details of the event. The structure of this object varies depending on the event type.
​
Timestamp
The timestamp of when the event occurred.

​
Authenticate Webhook Requests

The portal uses HMAC-SHA256 signatures to secure webhooks. Each webhook request includes a signature generated using the webhook secret key and the request payload. This allows the receiving application to verify the authenticity of the request and ensure that it has not been tampered with during transit. The signature is sent in the HTTP header: 
X-Signature-SHA256: <hex-encoded-hmac-signature>
The webhook secret key is configured in your portal configuration file or via environment variable: 
Webhooks:
  Secret: "your-secret-key-here"
  Provider: "db"
  PauseDuration: 5
  CacheExpiration: 300
  CacheCleanupInterval: 5
  TotalWorkers: 10
  HTTPTimeout: 60
  QueueSize: 1000
  Disable: false

​
Error Handling and Retries

If a webhook delivery fails, Tyk will not automatically retry the request. It is the responsibility of the receiving application to handle delivery failures. Strategies for managing delivery failures:
  • Implement a retry mechanism in your application with exponential backoff.
  • Use a message queue to buffer webhook payloads and ensure that they are processed even if your application is temporarily unavailable.

​
Best Practices

  • Idempotency: Design your webhook handler to be idempotent, meaning that it can safely receive the same webhook payload multiple times without causing any unintended side effects.
  • Payload Validation: Validate the payload of every webhook request to ensure that it is well-formed and that it has not been tampered with.