{"__v":16,"_id":"5699b35bcb127f0d003cc1ba","category":{"__v":11,"_id":"551ef4ef4986f62b00a7203e","pages":["551ef4f04986f62b00a7206d","551ef4f04986f62b00a7206e","551ef4f04986f62b00a7206f","552359b8e20da719000e797b","5536d74bc36ca60d003c5540","5548372bd2c8410d006c212d","55d77b86f662951900fc0ef5","5605b89024c9d80d001551fd","5668806406039e0d00c4ed24","56688887ee1dbf0d008f62a7","568c6de813c5ad0d00b34e4d","5699b35bcb127f0d003cc1ba","56cbe4638df25d0b00e8d774"],"project":"542b6018044e1e2200413772","version":"551ef4ef4986f62b00a7202e","reference":false,"createdAt":"2015-03-24T04:27:30.031Z","from_sync":false,"order":7,"slug":"website-push","title":"Website Push"},"parentDoc":null,"project":"542b6018044e1e2200413772","user":"55c146fdc0777c0d0046769d","version":{"__v":7,"_id":"551ef4ef4986f62b00a7202e","forked_from":"542b6018044e1e2200413775","project":"542b6018044e1e2200413772","createdAt":"2015-04-03T20:15:43.149Z","releaseDate":"2015-04-03T20:15:43.149Z","categories":["551ef4ef4986f62b00a7202f","551ef4ef4986f62b00a72030","551ef4ef4986f62b00a72031","551ef4ef4986f62b00a72032","551ef4ef4986f62b00a72033","551ef4ef4986f62b00a72034","551ef4ef4986f62b00a72035","551ef4ef4986f62b00a72036","551ef4ef4986f62b00a72037","551ef4ef4986f62b00a72038","551ef4ef4986f62b00a72039","551ef4ef4986f62b00a7203a","551ef4ef4986f62b00a7203b","551ef4ef4986f62b00a7203c","551ef4ef4986f62b00a7203d","551ef4ef4986f62b00a7203e","55d7f1879510f00d007ec727","56b94a5a9fc0de1700b60ae9","56bd0e48ac1c5c1900b2dbe4","56d74afc3eb4dd0b0020196a","5723ab8a1f41110e003081ed","576b4dd327d6252b00085422"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"updates":[],"createdAt":"2016-01-16T03:04:59.662Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":12,"body":"Use webhooks to get notified when a notification is displayed or clicked.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Introduction\"\n}\n[/block]\nWebhooks are HTTP `POST` calls to a URL you choose when a certain event occurs. You provide the base URL which will be POSTed to, and we will POST the notification data (title, message, icon, url, etc...) along with all custom data you sent with the notification.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Which events can I listen to?\"\n}\n[/block]\n- `notification.displayed`\n  This event occurs after a notification is displayed.\n\n- `notification.clicked`\n  This event occurs after a notification is clicked.\n\n- `notification.dismissed`\n  This event occurs after a notification is intentionally dismissed by the user (clicking the notification body or one of the notification action buttons *does not trigger* the dismissed webhook), after a group of notifications are all dismissed (with this notification as part of that group), or after a notification expires on its own time and disappears. This event is supported on Chrome only.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"How do I enable webhooks?\"\n}\n[/block]\nIn your `OneSignal.init()` method, add the following parameter:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Do NOT call init twice, use existing init\\nOneSignal.push([\\\"init\\\", {\\n  // Your other settings\\n  webhooks: {\\n    cors: false, // Defaults to false if omitted\\n    'notification.displayed': 'YOUR_WEBHOOK_URL', // e.g. https://site.com/hook\\n    'notification.clicked': 'YOUR_WEBHOOK_URL',\\n    // ... follow the same format for any event in the list above\\n  }\\n}]);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n`cors`: Defaults to `false`. Enable this setting only if your server has CORS enabled and supports non-simple CORS requests. If this setting is disabled, your webhook will not need CORS to receive data, but it will not receive the custom headers. See below. The simplest option is to leave it disabled.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"How many webhooks can I set per event?\"\n}\n[/block]\nAt the current time, you may only set one webhook URL per event.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"What requests do my webhooks receive?\"\n}\n[/block]\nRegardless of which event your webhook subscribes to, each request is formatted identically. The request your webhook receives depends on whether you enabled `cors`.\n\n## Request with CORS Disabled\n\nIf `cors` is set to `false`, your server *will not receive any custom headers*, and **will not receive** the header `Content-Type: application/json`. Your server will only receive our request payload, which is similar to the following:\n\n**Example Request Payload:**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"event\\\": \\\"notification.clicked\\\",\\n\\t\\\"id\\\": \\\"ed46884e-0e3f-4373-9e11-e28f27746d3d\\\",\\n  \\\"userId\\\": \\\"8086231d-97fc-4065-999e-1c7ea5e540b9\\\",\\n\\t\\\"heading\\\": \\\"Notification title\\\",\\n\\t\\\"content\\\": \\\"Notification message\\\",\\n\\t\\\"url\\\": \\\"https://site.com/notification_url_to_launch\\\",\\n\\t\\\"icon\\\": \\\"https://onesignal.com/images/notification_logo.png\\\",\\n\\t\\\"data\\\": {\\n    \\\"key1\\\": \\\"value1\\\",\\n    \\\"key2\\\": \\\"value2\\\"\\n  },\\n  \\\"action\\\": \\\"\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nIf, when initially sending the notification, a certain field is not provided (e.g. you don't include an icon, or you don't send specific data, or you don't specify a launch URL), then the corresponding field will not be included in the request payload.\n\n`event`: The string event type you subscribed to.\n`id`: The OneSignal notification ID of the notification.\n`userId`: The OneSignal user ID the notification was sent to.\n`url`: The URL to launch when the notification is clicked.\n`data`: Custom data you included when you sent the notification. In the REST API, this is the `data` field when creating the notification. On the online dashboard, this is also the `data` field under Options.\n`action`: This field is only included for the notification clicked webhook. An empty string indicates that the notification body was clicked. Any other string with a value corresponds to the ID of the action button that was clicked. The ID is a string you define (e.g. 'top-button', 'like-button') either using our dashboard or API when sending.\n\n## Request with CORS Enabled\n\nIf `cors` is set to `true`, your server will receive the following custom headers in addition to those set by the browser:\n\n**Request Headers**:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Content-Type: application/json\\nX-OneSignal-Event: EVENT_NAME\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\n**Example Request Payload:**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"event\\\": \\\"notification.clicked\\\",\\n\\t\\\"id\\\": \\\"ed46884e-0e3f-4373-9e11-e28f27746d3d\\\",\\n  \\\"userId\\\": \\\"8086231d-97fc-4065-999e-1c7ea5e540b9\\\",\\n\\t\\\"heading\\\": \\\"Notification title\\\",\\n\\t\\\"content\\\": \\\"Notification message\\\",\\n\\t\\\"url\\\": \\\"https://site.com/notification_url_to_launch\\\",\\n\\t\\\"icon\\\": \\\"https://onesignal.com/images/notification_logo.png\\\",\\n\\t\\\"data\\\": {\\n    \\\"key1\\\": \\\"value1\\\",\\n    \\\"key2\\\": \\\"value2\\\"\\n  },\\n  \\\"action\\\": \\\"\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nIf, when initially sending the notification, a certain field is not provided (e.g. you don't include an icon, or you don't send specific data, or you don't specify a launch URL), then the corresponding field will not be included in the request payload.\n\n`event`: The string event type you subscribed to.\n`id`: The OneSignal notification ID of the notification.\n`userId`: The OneSignal user ID the notification was sent to.\n`url`: The URL to launch when the notification is clicked.\n`data`: Custom data you included when you sent the notification. In the REST API, this is the `data` field when creating the notification. On the online dashboard, this is also the `data` field under Options.\n`action`: This field is only included for the notification clicked webhook. An empty string indicates that the notification body was clicked. Any other string with a value corresponds to the ID of the action button that was clicked. The ID is a string you define (e.g. 'top-button', 'like-button') either using our dashboard or API when sending.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Do I receive different payloads with CORS disabled?\"\n}\n[/block]\nNo -- your server will receive the same payload whether the `cors` flag is enabled or disabled. The only additional benefit enabling `cors` gives you is two extra HTTP headers that tell you the correct content type (the payload you receive is always JSON anyways) and the webhook event type without having to parse the body.","excerpt":"","slug":"webhooks","type":"basic","title":"Webhooks"}

Introduction

iOS

Android

Amazon

Windows Phone

Chrome Apps/Extensions

Mac OS X

Website Push

Corona SDK

Unity SDK

Marmalade SDK

Adobe Air

PhoneGap, Cordova, Ionic

Xamarin SDK

React Native

Cocos2d-x

Server REST API

Troubleshooting

Miscellaneous

Webhooks

Use webhooks to get notified when a notification is displayed or clicked. [block:api-header] { "type": "basic", "title": "Introduction" } [/block] Webhooks are HTTP `POST` calls to a URL you choose when a certain event occurs. You provide the base URL which will be POSTed to, and we will POST the notification data (title, message, icon, url, etc...) along with all custom data you sent with the notification. [block:api-header] { "type": "basic", "title": "Which events can I listen to?" } [/block] - `notification.displayed` This event occurs after a notification is displayed. - `notification.clicked` This event occurs after a notification is clicked. - `notification.dismissed` This event occurs after a notification is intentionally dismissed by the user (clicking the notification body or one of the notification action buttons *does not trigger* the dismissed webhook), after a group of notifications are all dismissed (with this notification as part of that group), or after a notification expires on its own time and disappears. This event is supported on Chrome only. [block:api-header] { "type": "basic", "title": "How do I enable webhooks?" } [/block] In your `OneSignal.init()` method, add the following parameter: [block:code] { "codes": [ { "code": "// Do NOT call init twice, use existing init\nOneSignal.push([\"init\", {\n // Your other settings\n webhooks: {\n cors: false, // Defaults to false if omitted\n 'notification.displayed': 'YOUR_WEBHOOK_URL', // e.g. https://site.com/hook\n 'notification.clicked': 'YOUR_WEBHOOK_URL',\n // ... follow the same format for any event in the list above\n }\n}]);", "language": "javascript" } ] } [/block] `cors`: Defaults to `false`. Enable this setting only if your server has CORS enabled and supports non-simple CORS requests. If this setting is disabled, your webhook will not need CORS to receive data, but it will not receive the custom headers. See below. The simplest option is to leave it disabled. [block:api-header] { "type": "basic", "title": "How many webhooks can I set per event?" } [/block] At the current time, you may only set one webhook URL per event. [block:api-header] { "type": "basic", "title": "What requests do my webhooks receive?" } [/block] Regardless of which event your webhook subscribes to, each request is formatted identically. The request your webhook receives depends on whether you enabled `cors`. ## Request with CORS Disabled If `cors` is set to `false`, your server *will not receive any custom headers*, and **will not receive** the header `Content-Type: application/json`. Your server will only receive our request payload, which is similar to the following: **Example Request Payload:** [block:code] { "codes": [ { "code": "{\n\t\"event\": \"notification.clicked\",\n\t\"id\": \"ed46884e-0e3f-4373-9e11-e28f27746d3d\",\n \"userId\": \"8086231d-97fc-4065-999e-1c7ea5e540b9\",\n\t\"heading\": \"Notification title\",\n\t\"content\": \"Notification message\",\n\t\"url\": \"https://site.com/notification_url_to_launch\",\n\t\"icon\": \"https://onesignal.com/images/notification_logo.png\",\n\t\"data\": {\n \"key1\": \"value1\",\n \"key2\": \"value2\"\n },\n \"action\": \"\"\n}", "language": "json" } ] } [/block] If, when initially sending the notification, a certain field is not provided (e.g. you don't include an icon, or you don't send specific data, or you don't specify a launch URL), then the corresponding field will not be included in the request payload. `event`: The string event type you subscribed to. `id`: The OneSignal notification ID of the notification. `userId`: The OneSignal user ID the notification was sent to. `url`: The URL to launch when the notification is clicked. `data`: Custom data you included when you sent the notification. In the REST API, this is the `data` field when creating the notification. On the online dashboard, this is also the `data` field under Options. `action`: This field is only included for the notification clicked webhook. An empty string indicates that the notification body was clicked. Any other string with a value corresponds to the ID of the action button that was clicked. The ID is a string you define (e.g. 'top-button', 'like-button') either using our dashboard or API when sending. ## Request with CORS Enabled If `cors` is set to `true`, your server will receive the following custom headers in addition to those set by the browser: **Request Headers**: [block:code] { "codes": [ { "code": "Content-Type: application/json\nX-OneSignal-Event: EVENT_NAME", "language": "http" } ] } [/block] **Example Request Payload:** [block:code] { "codes": [ { "code": "{\n\t\"event\": \"notification.clicked\",\n\t\"id\": \"ed46884e-0e3f-4373-9e11-e28f27746d3d\",\n \"userId\": \"8086231d-97fc-4065-999e-1c7ea5e540b9\",\n\t\"heading\": \"Notification title\",\n\t\"content\": \"Notification message\",\n\t\"url\": \"https://site.com/notification_url_to_launch\",\n\t\"icon\": \"https://onesignal.com/images/notification_logo.png\",\n\t\"data\": {\n \"key1\": \"value1\",\n \"key2\": \"value2\"\n },\n \"action\": \"\"\n}", "language": "json" } ] } [/block] If, when initially sending the notification, a certain field is not provided (e.g. you don't include an icon, or you don't send specific data, or you don't specify a launch URL), then the corresponding field will not be included in the request payload. `event`: The string event type you subscribed to. `id`: The OneSignal notification ID of the notification. `userId`: The OneSignal user ID the notification was sent to. `url`: The URL to launch when the notification is clicked. `data`: Custom data you included when you sent the notification. In the REST API, this is the `data` field when creating the notification. On the online dashboard, this is also the `data` field under Options. `action`: This field is only included for the notification clicked webhook. An empty string indicates that the notification body was clicked. Any other string with a value corresponds to the ID of the action button that was clicked. The ID is a string you define (e.g. 'top-button', 'like-button') either using our dashboard or API when sending. [block:api-header] { "type": "basic", "title": "Do I receive different payloads with CORS disabled?" } [/block] No -- your server will receive the same payload whether the `cors` flag is enabled or disabled. The only additional benefit enabling `cors` gives you is two extra HTTP headers that tell you the correct content type (the payload you receive is always JSON anyways) and the webhook event type without having to parse the body.