> For the complete documentation index, see [llms.txt](https://docs.adsecure.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.adsecure.com/docs/guides/notification-service.md). # Configuring the Notification Service In this guide we're going to see how you can be notified automatically when an [analysis](/docs/development/concepts.md#analysis) is completed. > If you're not familiar with GraphQL, please have a look at its [dedicated section](/docs/graphql/overview.md) in this documentation. In order to help you to use AdSecure with your infrastructure, we've developed a notification service that aims to keep you informed about the status of each [analysis](/docs/development/concepts.md#analysis). This service is going to notify you, for example, when an [analysis](/docs/development/concepts.md#analysis) is completed, when the AdSecure [crawler](/docs/development/concepts.md#crawler) has found a [violation](/docs/development/concepts.md#violation) or an [alert](/docs/development/concepts.md#alert), etc... ## Prerequisites Before starting this guide, please be sure that you're ready to use our service by following the steps illustrated in the [Quickstart](/docs/development/quickstart.md) section. ## Simple case — HTTP callback A [notification](/docs/development/concepts.md#notification) could sent by using different medium to inform you about the [analysis](/docs/development/concepts.md#analysis)'s status. For this simple example, Let's create a notification setting that's going to send us back an HTTP request each time the AdSecure crawler find a violation. In a similar way we've created an [`Analysis`](/api/graphql/analysis.md) in the [First Analysis](/docs/guides/first-analysis.md) guide, we're going to create a new [Notification](/api/graphql/notification.md) entry by sending to the GraphQL API a `mutation` query. When you want to create a [Notification](/api/graphql/notification.md), the following parameters are required to be set in the `input`: * The `name` which is going to help us to easily remember the scope of this notification. This value is also going to be used to generate the notification's login. * The `uri` which is representing the endpoint where you would like to receive this notification. In this example, we're going to use the [webhook.site](https://webhook.site/) service in order to simplify the flow, but feel free to use the endpoint of your choice. * The `trigger` that you want to subscribe to. This key could take one of the following values: * `ON_DONE`: It will cause the notification to be sent when the analysis has its status updated as `DONE`. * `ON_ERROR`: It will cause the notification to be sent when the analysis has its status updated as `ERROR`. * `ON_VIOLATION`: It will cause the notification to be sent if at least one [violation](/docs/development/concepts.md#violation) was found during the analysis. * `ON_ALERT`: It will cause the notification to be sent if at least one [violation](/docs/development/concepts.md#violation) that is considered as an [alert](/docs/development/concepts.md#alert) was found during the analysis. **Query** ```bash mutation { createNotification(input: { name: "Notify me on violation", uri: "https://webhook.site/6ca79585-db5d-43ba-9eee-c9206c6544f6", trigger: ON_VIOLATION }) { login } } ``` **Response** ```json { "data": { "createNotification": { "login": "notify-me-on-violation" } } } ``` We can now use this notification setting when we create a new analysis. We need for that to set the notification's login as an additional parameter to the example illustrated in the [First Analysis](/docs/guides/first-analysis.md)'s guide and we ask the API to return us an additional field `notifications` as feedback. As you can see, you can add multiple notification settings to a single [`Analysis`](/api/graphql/analysis.md), if you like for example to be notified on multiple triggers and or different endpoints. **Query** ```bash mutation { createAnalysis(input: { url: "https://examples.adsecure.com/404", notifications: [ "notify-me-on-violation" ] }) { id notifications { trigger uri } } } ``` **Response** ```json { "data": { "createAnalysis": { "id": "YW5hbHlzaXN8YThiYzk0M2ItNTY3ZS00NzA5LWIwOWItMTI1YmMzNGMxMjUwfDIwMTgtMDktMDI=", "notifications": [ { "trigger": "ON_VIOLATION", "uri": "https://webhook.site/6ca79585-db5d-43ba-9eee-c9206c6544f6" } ] } } } ``` If you open the web page related to your notification's URI (i.e. adding the `#` character to the current URI) you'll be able to see the [notification](/docs/development/concepts.md#notification) sent by our service: `https://webhook.site/#/6ca79585-db5d-43ba-9eee-c9206c6544f6` A [notification](/docs/development/concepts.md#notification) is sent as a `POST` request with the following payload: ```json { "id": "YW5hbHlzaXN8YThiYzk0M2ItNTY3ZS00NzA5LWIwOWItMTI1YmMzNGMxMjUwfDIwMTgtMDktMDI=", "object": "RECOGNITION", "trigger": "ON_VIOLATION", "report": "https://s3.amazonaws.com/adsecure/analysis/year=2018/month=9/day=4/YW5hbHlzaXN8YThiYzk0M2ItNTY3ZS00NzA5LWIwOWItMTI1YmMzNGMxMjUwfDIwMTgtMDktMDI=.json", } ``` If we take each element of this payload one by one we have: * `id` which represents the [`Analysis`](/api/graphql/analysis.md)'s `id` that is related to this notification. * `report` which provide you the detailed version of an analysis. * `trigger` which represent your subscription. That's all for this guide, feel free to use this notification service as you like! --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.adsecure.com/docs/guides/notification-service.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.