Chat Webhooks

Use webhooks with Photon Cloud to have more control over your chat applications. You can persist channel history, filter messages, cancel channel creation and even prohibit certain players from subscribing to chat channels.

Photon Chat webhooks are event-driven HTTP POST requests sent by Photon Cloud to specific URLs. Each Photon Chat webhook is defined by its own triggers, data and destination path.

Contents

Setup

Basic Settings

  • BaseUrl (required)
    The URL for the service hosting your hooks. It must not end with a forward slash. Callbacks are received at the relative path URIs of the configured hooks. Read this if the value you want to configure will contain a query string.
  • CustomHttpHeaders
    JSON string of key/value pairs (string:string) that should be set as HTTP headers in any request made to the configured web service. Read more here.

Back To Top

Paths

Configure each path to receive events at the URIs each identifies on your host. Any path that is left empty will not be hit, you will not receive any callbacks on the affected webhook. Read this if the value you want to configure will contain a query string.

  • PathChannelCreate
    Called when a new channel is created or when its state needs to be loaded from external service.
  • PathChannelDestroy
    Called when a channel is removed from Photon servers memory. If IsPersistent is set to true the channel state is sent.
  • PathChannelSubscribe
    Called when a player subscribes to an already created channel.
  • PathChannelUnsubscribe
    Called when a player unsubscribes from a channel.
  • PathPublishMessage
    Called when the client publishes a message in a channel or sends a private message. The client should explicitly choose to HTTP forward the message as a webhook.

Back To Top

Options

Fine-tune the behaviour of your chat webhooks configuration with these options. An option is considered not configured when not set up or if its value is left empty.

  • FailIfUnavailable
    If set to true, channel creation, subscription and publish message operations will fail when the corresponding hook's configured endpoint is not available. An endpoint is considered unavailable when an error occurs during the process of its HTTP request or when the HTTP response is not successful. Default is false.
  • IsPersistent
    If set to true, Photon Cloud sends the channel state before destroying it. This option is only valid when both PathChannelCreate and PathChannelDestory are properly configured and MaxChannelHistory is greater than 0. For more information please read more about ChannelCreate and ChannelDestroy webhooks. Default is false.
  • MaxChannelHistory Maximum number of messages to be persisted per channel. It should be between 1 and 100. Default is 100.
  • HasErrorInfo If set to true, Chat clients will be notified with an error message when a hook endpoint (PathUnsubscribe or PathChannelDestory excluded) is unavailable but FailIfUnavailable is set to false. Default is false.
  • SkipPostCreationFailure If set to true, PathUnsubscribe and PathChannelDestory webhooks will not be sent after a channel creation failure. Default is false.

Back To Top

Query String Handling

Query string parameters can be included in the BaseUrl or in the Paths. If you do use them you should know the following:

  • Query string parameters are parsed using UTF8 encoding.
  • If multiple occurrences of the same query string parameter are found in the same setting, a single parameter will be used with a comma separating each value. The comma will be escaped using %2c.
  • If the same parameter key is used in BaseUrl and in a configured Path then the value from the Path setting will be used.
  • Parameters without values are allowed.
  • Parameters without keys are allowed. The key is considered an empty string. If one or parameters missing keys are found in both BaseUrl and a configured Path, only those in the configured Path will be used.
  • Query string parameters will be URL encoded.
  • You can use URL tags in query string parameters.

Example:

  • Configuration:

    • BaseUrl:
              https://myawesomegame.com/chat/webhooks?clientver={AppVersion}&key=&keyA=valueA&keyA=valueB&keyB=valueB&=value
    • PathChannelCreate: create?key=X&keyA=valueC
    • PathChannelDestroy: destroy?keyB=valueC&keyC=valueC&=valueD&=valueE
  • Resulting URLs:

    • PathChannelCreate:
              https://myawesomegame.com/chat/webhooks/create?clientver=1.0&key=X&keyA=valueC&keyB=valueB&=value
    • PathChannelDestroy:
              https://myawesomegame.com/chat/webhooks/destroy?clientver=1.1&key=&keyA=valueA%2cvalueB&keyB=valueC&keyC=valueC&=valueD%2cvalueE

Back To Top

HTTP Headers Considerations

There are few things you need to consider when using custom HTTP headers:

  • The value of CustomHttpHeaders configuration key needs to be a stringified JSON object that has properties with string values only. The JSON object's properties' names will be used as HTTP request header field names and the properties' values will be used as their respective values.
    Example:

    • CustomHttpHeaders value:
              {'X-Secret': 'YWxhZGRpbjpvcGVuc2VzYW1l', 'X-Origin': 'Photon'}
    • Webhooks HTTP request headers:
              X-Secret: YWxhZGRpbjpvcGVuc2VzYW1l
      X-Origin: Photon
  • Custom HTTP headers field names are case sensitive.

  • The following HTTP headers are restricted and will be ignored if set from the "CustomHttpHeaders" configuration value.

    • Connection
    • Content-Length
    • Host
    • Range
    • Proxy-Connection
    • Accept
    • Content-Type
    • Date
    • Expect
    • If-Modified-Since
    • Referer
    • Transfer-Encoding
    • User-Agent

Back To Top

Common Request Arguments

AppId: AppId of your application as set from the game client and found in the dashboard.

AppVersion: Version of your application as set from the game client.

Region: Has the region to which the game client is connected to and to which the room in question belongs to.

ChannelType: The channel type: "Public" for public channels and "Private" for private channels.

UserId: UserID of the player triggering the hook. (Except ChannelDestory)

HistoryCount: The current count of messages in the channel history. (Except ChannelDestory)

ChannelName: The name of the channel in which the hook is triggered. (Only public channels)

UsersPair: Array of two strings containing the UserIDs of the two ends of the private channel. (Only private channels)

Back To Top

Request Arguments List

This table gives you what arguments are available for each webhook for public channels:

Argument ChannelCreate /
ChannelSubscribe
ChannelDestroy PublishMessage ChannelUnsubscribe
AppId
AppVersion
Region
ChannelType ("Public")
ChannelName
HistoryLen
HistoryCount
UserId
ChannelState (conditions apply)
Message

For private channels, there is a single webhook PublishMessage with teh following arguments:

  • AppId
  • AppVersion
  • Region
  • ChannelType (set to "Private")
  • UsersPair
  • HistoryCount
  • UserId

Back To Top

Paths In Details

ChannelCreate

This webhook is sent when a channel is about to be created on Photon servers. If you have a previously saved the ChannelState, you need to return it in the webhooks response to load its history. See "Return Values" for an example.

Back To Top

Specific Arguments

HistoryLen: It forwards the parameter with same name set by client in subscribe operation. It contains the number of messages from the history requested by the client.

Sample Call

{
   "AppId":"00000000-0000-0000-0000-000000000000",
   "AppVersion":"1.0",
   "Region":"EU",
   "ChannelType":"Public",
   "ChannelName":"PersistentChannel",
   "HistoryLen":10,
   "UserId":"testClient1"
}

Back To Top

ChannelDestroy

This webhook is sent when a channel is about to be destroyed on Photon servers. This happens when an empty channel times out. A channel is considered empty when it does not contain any subscriber, because they left. Default empty channel timeout value is 5 seconds. If IsPersistent is set to true and PathChannelDestory is configured properly, ChannelState will be sent in the webhook body. In the ChannelState, the History object is just for debugging purposes. You may discard it. Photon servers use the BinaryHistory to persist data types. You should save it as is if you want to load channel history later.

Back To Top

Specific Arguments

ChannelState: A serializable channel state.

Sample Call

{
   "AppId":"00000000-0000-0000-0000-000000000000",
   "AppVersion":"1.0",
   "Region":"EU",
   "ChannelType":"Public",
   "ChannelName":"PersistentChannel",
   "HistoryCount":2,
   "ChannelState":{
      "ChannelHistoryCapacity":100,
      "BinaryHistory": "RGl6AAEAAAAAAAN6AANp..",
      "History":{
         "MessageIdBase":2,
         "Entries":[
            {
               "Message":"msg1",
               "Sender":"testClient1",
               "MsgId":1
            },
            {
               "Message":"msg2",
               "Sender":"testClient2",
               "MsgId":2
            }
         ]
      }
   }
}

Back To Top

ChannelSubscribe

This webhook is triggered by client subscription to an already created channel. The client is either:

  • not the first subscriber. This should be the most frequent case.
  • the first subscriber when the channel is empty and did not time out. This is unlikely because it is a small window.

Back To Top

Specific Arguments

HistoryLen: It forwards the parameter with same name set by client in subscribe operation. It contains the number of messages from the history requested by the client.

Sample Call

{
   "AppId":"00000000-0000-0000-0000-000000000000",
   "AppVersion":"1.0",
   "Region":"EU",
   "ChannelType":"Public",
   "ChannelName":"PersistentChannel",
   "HistoryLen":-1,
   "HistoryCount": 1,
   "UserId":"testClient2"
}

Back To Top

ChannelUnsubscribe

This webhook is triggered when a client disconnects from a channel, which can be caused by any of the following reasons:

  • explicit call to unsubscribe operation.
  • explicit disconnection.
  • timeout disconnection.
  • channel creation failure and SkipPostCreationFailure is set to false.
  • subscription failure.

Back To Top

Specific Arguments

ChannelUnsubscribe has no extra arguments.

Sample Call

{
   "AppId":"00000000-0000-0000-0000-000000000000",
   "AppVersion":"1.0",
   "Region":"EU",
   "ChannelType":"Public",
   "ChannelName":"PersistentChannel",
   "HistoryCount":2,
   "UserId":"testClient2"
}

Back To Top

PublishMessage

This webhook is triggered when a client publishes a message into the channel or sends a private message to a user. The client should explicitly choose to HTTP forward the message as a webhook using the appropriate WebFlag. If you want to replace the message to be published you can return the new one in Data parameter. The value of the returned webhook response's Data property will be published inside the channel instead of the original message content sent by the client. See "Return Values" for an example.

You can choose any type of data as long as it is supported by Photon serialization. One use case for this could be data polling from the web server. Also making use of the Data return parameter may result in a behavior that could be compared to Photon Realtime's WebRPC.

Back To Top

Specific Arguments

Message: Message to be published to all subscribers of the channel. Forwarded as sent from client.

Public Channel: Sample Call

{
   "AppId":"00000000-0000-0000-0000-000000000000",
   "AppVersion":"1.0",
   "Region":"EU",
   "ChannelType":"Public",
   "ChannelName":"PersistentChannel",
   "HistoryCount":1,
   "UserId":"testClient2",
   "Message":"msg2"
}

Private Channel: Sample Call

{
   "AppId":"00000000-0000-0000-0000-000000000000",
   "AppVersion":"1.0",
   "Region":"EU",
   "ChannelType":"Private",
   "UsersPair":["testClient1", "testClient2"],
   "HistoryCount":1,
   "UserId":"testClient2",
   "Message":"msg2"
}

Back To Top

Return Values

All webhooks expect a JSON object containing a ResultCode which can be:

  • 0 for success.

Sample Success Response

{
   "ResultCode":0,
   "DebugMessage":"OK"
}
  • any other integer for failure.

Sample Failure Response

{
   "ResultCode":1,
   "DebugMessage":"A nice self-explanatory error message"
}

"PublishMessage" webhook supports an extra property from the web server which is Data.

Sample "Full" PublishMessage Response

{
   "ResultCode":0,
   "DebugMessage":"Message Will Be Overridden By Server",
   "Data": "Anything you want and supported by Photon Serialization"
}

"ChannelCreate" webhook supports an extra property from web server which is the ChannelState.

Sample "Full" ChannelCreate Response

{
   "ResultCode":0,
   "DebugMessage":"ChannelState Loaded Successfully",
   "ChannelState":{
      "ChannelHistoryCapacity":100,
      "BinaryHistory": "RGl6AAEAAAAAAAN6AANp..",
      "History":{
         "MessageIdBase":2,
         "Entries":[
            {
               "Message":"msg1",
               "Sender":"testClient1",
               "MsgId":1
            },
            {
               "Message":"msg2",
               "Sender":"testClient2",
               "MsgId":2
            }
         ]
      }
   }
}

Since "History" is not required for loading the state as it's useful for debugging, you may discard it when saving the state or when loading it.

Sample "Stripped" ChannelCreate Response

{
   "ResultCode":0,
   "DebugMessage":"ChannelState Loaded Successfully",
   "ChannelState":{
      "ChannelHistoryCapacity":100,
      "BinaryHistory": "RGl6AAEAAAAAAAN6AANp.."
   }
}

It is considered a best practice to:

  • have a list of reserved ResultCode values per custom user error type.
  • return a DebugMessage string which can be useful for debugging.

Back To Top

Response Arguments List

This table gives you what response arguments are supported for each webhook for public channels:

Argument ChannelCreate PublishMessage others
ResultCode
DebugMessage (optional) (optional) (optional)
Data (optional)
ChannelState (optional)

Back To Top

Cancelable Operations

The table below shows which chat operations could be canceled or aborted using webhooks. To do so you need to return a ResultCode other than 0 and optionally a DebugMessage that you can find in the OperationResponse's DebugMessage.

Webhook Can Be Canceled
ChannelCreate
ChannelDestory
ChannelSubscribe
ChannelUnsubscribe
PublishMessage

Back To Top

URL Tags

You can optionally set one or more "dynamic variables". Those variables will be replaced with their respective values in our backend before sending out any requests. Empty space characters will be removed.

URL tags come in handy if you want to handle user segments of your application differently, each. Photon supports the following URL tags:

  • {AppVersion} will pass the application version as set by the client, e.g. "1.0".
  • {AppId} will pass the ID of your application, e.g. "2afda618-e64f-4a85-b2a2-74e05fdf0b65".
  • {Region} will pass the token for the cloud region the triggering client is connected to, e.g. "EU" or "USW".
  • {Cloud} will pass the name of the cloud the triggering client is connected to, e.g. "public" or "enigmaticenterprise".

Back To Top

Examples Of URL Tags Use Cases

  1. https://{Region}.mydomain.com/{AppId}?version={AppVersion}&cloud={Cloud} to e.g. route each region to different hosts, version and cloud passed as query parameters.
  2. https://mydomain.com/{Cloud}/{Region}/{AppId}/{AppVersion} passes all tags as well structured URI.

Back To Top

Data Types Conversion

In this section, only the type of data exchanged between Photon server and the web service is explained. For more information about data types between clients and Photon servers please refer to serialization in Photon page.

Back To Top

Photon Server -> Web Service

C# / .Net (Photon supported types) JavaScript / JSON
byte number
short
int
long
double
bool bool
string string
byte[] (byte array length < short.MaxValue) string (Base64 encoded)
T[] (array of supported type T, length < short.MaxValue) array
Hashtable (of supported types, count < short.MaxValue, preferably Photon implementation) object
Dictionary (keys and values of supported types, count < short.MaxValue) object
null null

Back To Top

Sample Request Data (types Are Concatenated)

As sent from Photon Server:

As read by Web Service:

Back To Top

Web Service -> Photon Server

Here is a table that matches each JavaScript/JSON type to its equivalent one in C#/.Net :

JavaScript / JSON C# / .Net
object Dictionary
array object[] (array of objects)
number (integral) long
number (floating) double
string string
boolean bool
null (not a type) null
undefined (when sent) null

Back To Top

Sample Response Data (types Are Concatenated)

As sent from Web Service:

As read from Photon Server:

Back To Top

Securing Webhooks

Other than using HTTPS and newer TLS version, you can enforce webhooks security using custom HTTP request headers or query string parameters. The idea is that you set up one or more "secrets" ("token", "key", etc.) from Photon dashboard that can help you make sure that the incoming HTTP requests are originating from Photon servers.

To Document Top