> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md

# Manage notifications

> Learn how to use the Payabli API to add notifications and automated reports for important events

Use Payabli's notification functions to create and manage automated notifications and reports for important events. This guide covers the key operations for managing notifications through the API.

## Considerations

Keep these considerations in mind when working with notifications:

* Notifications can be configured at both organization and paypoint levels independently. Setting up the same notification at both levels results in duplicate notifications, as neither configuration overrides the other.
* Multiple notification methods are supported including email, SMS, webhooks, and automated reports.
* Each notification requires a specific event type to trigger it. Learn more about the events [here](/guides/pay-ops-notifications-webhooks-overview#notifications).
* Notifications can be set to run until cancelled or for a specific duration.
* For webhook notifications, you can include custom header parameters.

## Set the notification scope

Every notification belongs to either an organization or a paypoint. Two fields set this scope:

* `ownerType`: the type of entity that owns the notification. Accepted values:
  * `0`: organization or partner
  * `2`: paypoint
* `ownerId`: the ID of the owning entity. It's the `orgId` when `ownerType` is `0`, or the `paypointId` when `ownerType` is `2`.

The examples in this guide use `ownerType: 0` to scope notifications to an organization. To scope a notification to a paypoint instead, set `ownerType: 2` and pass the `paypointId` as `ownerId`:

```json
{
  "ownerType": 2,
  "ownerId": 3040,
  "method": "web",
  "frequency": "untilcancelled",
  "status": 1,
  "target": "https://webhook.site/2871b8f8-edc7-441a-b376-98d8c8e33275",
  "content": {
    "eventType": "CreatedApplication"
  }
}
```

## Create a notification

Send a POST request to `/api/Notification` to create a notification. The notification can be configured to trigger on specific events and deliver updates via email, SMS, or webhooks. See the [API reference](/developers/api-reference/notification/add-notification) for full documentation.

This example creates a webhook notification that triggers when an application is created:

### Request

POST [https://api-sandbox.payabli.com/api/Notification](https://api-sandbox.payabli.com/api/Notification)

```curl Webhook
curl -X POST https://api-sandbox.payabli.com/api/Notification \
     -H "requestToken: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "content": {
    "eventType": "CreatedApplication"
  },
  "frequency": "untilcancelled",
  "method": "web",
  "ownerId": 236,
  "ownerType": 0,
  "status": 1,
  "target": "https://webhook.site/2871b8f8-edc7-441a-b376-98d8c8e33275"
}'
```

```typescript Webhook
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient({
        apiKey: "YOUR_API_KEY_HERE",
    });
    await client.notification.addNotification({
        content: {
            eventType: "CreatedApplication",
        },
        frequency: "untilcancelled",
        method: "web",
        ownerId: 236,
        ownerType: 0,
        status: 1,
        target: "https://webhook.site/2871b8f8-edc7-441a-b376-98d8c8e33275",
    });
}
main();

```

```python Webhook
from payabli import payabli, NotificationStandardRequest, NotificationStandardRequestContent

client = payabli(
    api_key="YOUR_API_KEY_HERE",
)

client.notification.add_notification(
    request=NotificationStandardRequest(
        content=NotificationStandardRequestContent(
            event_type="CreatedApplication",
        ),
        frequency="untilcancelled",
        method="web",
        owner_id=236,
        owner_type=0,
        status=1,
        target="https://webhook.site/2871b8f8-edc7-441a-b376-98d8c8e33275",
    ),
)

```

```java Webhook
package com.example.usage;

import io.github.payabli.api.PayabliPayabliApiOasClient;
import io.github.payabli.api.types.AddNotificationRequest;
import io.github.payabli.api.types.NotificationStandardRequest;
import io.github.payabli.api.types.NotificationStandardRequestContent;
import io.github.payabli.api.types.NotificationStandardRequestContentEventType;
import io.github.payabli.api.types.NotificationStandardRequestFrequency;
import io.github.payabli.api.types.NotificationStandardRequestMethod;
import java.util.Optional;

public class Example {
    public static void main(String[] args) {
        PayabliPayabliApiOasClient client = PayabliPayabliApiOasClient
            .builder()
            .apiKey("YOUR_API_KEY_HERE")
            .build();

        client.notification().addNotification(
            AddNotificationRequest.of(
                NotificationStandardRequest
                    .builder()
                    .frequency(NotificationStandardRequestFrequency.UNTILCANCELLED)
                    .method(NotificationStandardRequestMethod.WEB)
                    .ownerType(0)
                    .target("https://webhook.site/2871b8f8-edc7-441a-b376-98d8c8e33275")
                    .content(
                        Optional.of(
                            NotificationStandardRequestContent
                                .builder()
                                .eventType(Optional.of(NotificationStandardRequestContentEventType.CREATED_APPLICATION))
                                .build()
                        )
                    )
                    .ownerId(Optional.of(236))
                    .status(Optional.of(1))
                    .build()
            )
        );
    }
}
```

```ruby Webhook
require "payabli"

client = Payabli::Client.new(api_key: "YOUR_API_KEY_HERE")

client.notification.add_notification(
  content: {
    event_type: "CreatedApplication"
  },
  frequency: "untilcancelled",
  method_: "web",
  owner_id: 236,
  owner_type: 0,
  status: 1,
  target: "https://webhook.site/2871b8f8-edc7-441a-b376-98d8c8e33275"
)

```

```csharp Webhook
using PayabliPayabliApiOas;
using System.Threading.Tasks;

namespace Usage;

public class Example
{
    public async Task Do() {
        var client = new PayabliPayabliApiOasClient(
            apiKey: "YOUR_API_KEY_HERE"
        );

        await client.Notification.AddNotificationAsync(
            new NotificationStandardRequest {
                Content = new NotificationStandardRequestContent {
                    EventType = NotificationStandardRequestContentEventType.CreatedApplication
                },
                Frequency = NotificationStandardRequestFrequency.Untilcancelled,
                Method = NotificationStandardRequestMethod.Web,
                OwnerId = 236,
                OwnerType = 0,
                Status = 1,
                Target = "https://webhook.site/2871b8f8-edc7-441a-b376-98d8c8e33275"
            }
        );
    }

}

```

```go Webhook
package example

import (
    context "context"

    payabli "github.com/payabli/sdk-go"
    client "github.com/payabli/sdk-go/client"
    option "github.com/payabli/sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithApiKey(
            "YOUR_API_KEY_HERE",
        ),
    )
    request := &payabli.AddNotificationRequest{
        NotificationStandardRequest: &payabli.NotificationStandardRequest{
            Content: &payabli.NotificationStandardRequestContent{
                EventType: payabli.NotificationStandardRequestContentEventTypeCreatedApplication.Ptr(),
            },
            Frequency: payabli.NotificationStandardRequestFrequencyUntilcancelled,
            Method: payabli.NotificationStandardRequestMethodWeb,
            OwnerId: payabli.Int(
                236,
            ),
            OwnerType: 0,
            Status: payabli.Int(
                1,
            ),
            Target: "https://webhook.site/2871b8f8-edc7-441a-b376-98d8c8e33275",
        },
    }
    client.Notification.AddNotification(
        context.TODO(),
        request,
    )
}

```

```php Webhook
<?php

namespace Example;

use Payabli\PayabliClient;
use Payabli\Types\NotificationStandardRequest;
use Payabli\Types\NotificationStandardRequestContent;
use Payabli\Types\NotificationStandardRequestContentEventType;
use Payabli\Types\NotificationStandardRequestFrequency;
use Payabli\Types\NotificationStandardRequestMethod;

$client = new PayabliClient(
    apiKey: 'YOUR_API_KEY_HERE',
);
$client->notification->addNotification(
    new NotificationStandardRequest([
        'content' => new NotificationStandardRequestContent([
            'eventType' => NotificationStandardRequestContentEventType::CreatedApplication->value,
        ]),
        'frequency' => NotificationStandardRequestFrequency::Untilcancelled->value,
        'method' => NotificationStandardRequestMethod::Web->value,
        'ownerId' => 236,
        'ownerType' => 0,
        'status' => 1,
        'target' => 'https://webhook.site/2871b8f8-edc7-441a-b376-98d8c8e33275',
    ]),
);

```

```swift Webhook
import Foundation

let headers = [
  "requestToken": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "content": ["eventType": "CreatedApplication"],
  "frequency": "untilcancelled",
  "method": "web",
  "ownerId": 236,
  "ownerType": 0,
  "status": 1,
  "target": "https://webhook.site/2871b8f8-edc7-441a-b376-98d8c8e33275"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/Notification")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

A successful response will return the ID of the created notification:

### Response (200)

```json
{
  "responseText": "Success",
  "isSuccess": true,
  "responseCode": 1,
  "responseData": 1717
}
```

## Get notification details

Send a GET request to `/api/Notification/{notificationId}` to retrieve information about a specific notification. See the [API reference](/developers/api-reference/notification/get-notification) for full documentation.

This example retrieves details for notification ID `1717`:

### Request

GET [https://api-sandbox.payabli.com/api/Notification/\{nId}](https://api-sandbox.payabli.com/api/Notification/\{nId})

```curl
curl https://api-sandbox.payabli.com/api/Notification/1717 \
     -H "requestToken: <apiKey>"
```

```typescript
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient({
        apiKey: "YOUR_API_KEY_HERE",
    });
    await client.notification.getNotification("1717");
}
main();

```

```python
from payabli import payabli

client = payabli(
    api_key="YOUR_API_KEY_HERE",
)

client.notification.get_notification(
    n_id="1717",
)

```

```java
package com.example.usage;

import io.github.payabli.api.PayabliPayabliApiOasClient;

public class Example {
    public static void main(String[] args) {
        PayabliPayabliApiOasClient client = PayabliPayabliApiOasClient
            .builder()
            .apiKey("YOUR_API_KEY_HERE")
            .build();

        client.notification().getNotification("1717");
    }
}
```

```ruby
require "payabli"

client = Payabli::Client.new(api_key: "YOUR_API_KEY_HERE")

client.notification.get_notification(n_id: "1717")

```

```csharp
using PayabliPayabliApiOas;
using System.Threading.Tasks;

namespace Usage;

public class Example
{
    public async Task Do() {
        var client = new PayabliPayabliApiOasClient(
            apiKey: "YOUR_API_KEY_HERE"
        );

        await client.Notification.GetNotificationAsync(
            "1717"
        );
    }

}

```

```go
package example

import (
    context "context"

    client "github.com/payabli/sdk-go/client"
    option "github.com/payabli/sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithApiKey(
            "YOUR_API_KEY_HERE",
        ),
    )
    client.Notification.GetNotification(
        context.TODO(),
        "1717",
    )
}

```

```php
<?php

namespace Example;

use Payabli\PayabliClient;

$client = new PayabliClient(
    apiKey: 'YOUR_API_KEY_HERE',
);
$client->notification->getNotification(
    '1717',
);

```

```swift
import Foundation

let headers = ["requestToken": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/Notification/1717")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

A successful response returns the details of the notification:

### Response (200)

```json
{
  "content": {
    "fileFormat": "csv",
    "reportName": "Returned"
  },
  "createdAt": "2024-02-21T09:16:31Z",
  "frequency": "weekly",
  "lastUpdated": "2024-02-21T09:16:31Z",
  "method": "report-email",
  "notificationId": 1717,
  "ownerId": 123,
  "ownerName": "The Pilgrim Planner",
  "ownerType": 0,
  "status": 1,
  "target": "admin@business.com"
}
```

## Update a notification

Send a PUT request to `/api/Notification/{notificationId}` to modify an existing notification's configuration. See the [API reference](/developers/api-reference/notification/update-notification) for full documentation.

This example updates a notification to use a different webhook URL and adds a new header parameter:

### Request

PUT [https://api-sandbox.payabli.com/api/Notification/\{nId}](https://api-sandbox.payabli.com/api/Notification/\{nId})

```curl
curl -X PUT https://api-sandbox.payabli.com/api/Notification/1717 \
     -H "requestToken: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "content": {
    "eventType": "ApprovedPayment"
  },
  "frequency": "untilcancelled",
  "method": "email",
  "ownerId": 136,
  "ownerType": 0,
  "status": 1,
  "target": "newemail@email.com"
}'
```

```typescript
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient({
        apiKey: "YOUR_API_KEY_HERE",
    });
    await client.notification.updateNotification("1717", {
        content: {
            eventType: "ApprovedPayment",
        },
        frequency: "untilcancelled",
        method: "email",
        ownerId: 136,
        ownerType: 0,
        status: 1,
        target: "newemail@email.com",
    });
}
main();

```

```python
from payabli import payabli, NotificationStandardRequest, NotificationStandardRequestContent

client = payabli(
    api_key="YOUR_API_KEY_HERE",
)

client.notification.update_notification(
    n_id="1717",
    request=NotificationStandardRequest(
        content=NotificationStandardRequestContent(
            event_type="ApprovedPayment",
        ),
        frequency="untilcancelled",
        method="email",
        owner_id=136,
        owner_type=0,
        status=1,
        target="newemail@email.com",
    ),
)

```

```java
package com.example.usage;

import io.github.payabli.api.PayabliPayabliApiOasClient;
import io.github.payabli.api.types.NotificationStandardRequest;
import io.github.payabli.api.types.NotificationStandardRequestContent;
import io.github.payabli.api.types.NotificationStandardRequestContentEventType;
import io.github.payabli.api.types.NotificationStandardRequestFrequency;
import io.github.payabli.api.types.NotificationStandardRequestMethod;
import io.github.payabli.api.types.UpdateNotificationRequest;
import java.util.Optional;

public class Example {
    public static void main(String[] args) {
        PayabliPayabliApiOasClient client = PayabliPayabliApiOasClient
            .builder()
            .apiKey("YOUR_API_KEY_HERE")
            .build();

        client.notification().updateNotification(
            "1717",
            UpdateNotificationRequest.of(
                NotificationStandardRequest
                    .builder()
                    .frequency(NotificationStandardRequestFrequency.UNTILCANCELLED)
                    .method(NotificationStandardRequestMethod.EMAIL)
                    .ownerType(0)
                    .target("newemail@email.com")
                    .content(
                        Optional.of(
                            NotificationStandardRequestContent
                                .builder()
                                .eventType(Optional.of(NotificationStandardRequestContentEventType.APPROVED_PAYMENT))
                                .build()
                        )
                    )
                    .ownerId(Optional.of(136))
                    .status(Optional.of(1))
                    .build()
            )
        );
    }
}
```

```ruby
require "payabli"

client = Payabli::Client.new(api_key: "YOUR_API_KEY_HERE")

client.notification.update_notification(
  n_id: "1717",
  content: {
    event_type: "ApprovedPayment"
  },
  frequency: "untilcancelled",
  method_: "email",
  owner_id: 136,
  owner_type: 0,
  status: 1,
  target: "newemail@email.com"
)

```

```csharp
using PayabliPayabliApiOas;
using System.Threading.Tasks;

namespace Usage;

public class Example
{
    public async Task Do() {
        var client = new PayabliPayabliApiOasClient(
            apiKey: "YOUR_API_KEY_HERE"
        );

        await client.Notification.UpdateNotificationAsync(
            "1717",
            new NotificationStandardRequest {
                Content = new NotificationStandardRequestContent {
                    EventType = NotificationStandardRequestContentEventType.ApprovedPayment
                },
                Frequency = NotificationStandardRequestFrequency.Untilcancelled,
                Method = NotificationStandardRequestMethod.Email,
                OwnerId = 136,
                OwnerType = 0,
                Status = 1,
                Target = "newemail@email.com"
            }
        );
    }

}

```

```go
package example

import (
    context "context"

    payabli "github.com/payabli/sdk-go"
    client "github.com/payabli/sdk-go/client"
    option "github.com/payabli/sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithApiKey(
            "YOUR_API_KEY_HERE",
        ),
    )
    request := &payabli.UpdateNotificationRequest{
        NotificationStandardRequest: &payabli.NotificationStandardRequest{
            Content: &payabli.NotificationStandardRequestContent{
                EventType: payabli.NotificationStandardRequestContentEventTypeApprovedPayment.Ptr(),
            },
            Frequency: payabli.NotificationStandardRequestFrequencyUntilcancelled,
            Method: payabli.NotificationStandardRequestMethodEmail,
            OwnerId: payabli.Int(
                136,
            ),
            OwnerType: 0,
            Status: payabli.Int(
                1,
            ),
            Target: "newemail@email.com",
        },
    }
    client.Notification.UpdateNotification(
        context.TODO(),
        "1717",
        request,
    )
}

```

```php
<?php

namespace Example;

use Payabli\PayabliClient;
use Payabli\Types\NotificationStandardRequest;
use Payabli\Types\NotificationStandardRequestContent;
use Payabli\Types\NotificationStandardRequestContentEventType;
use Payabli\Types\NotificationStandardRequestFrequency;
use Payabli\Types\NotificationStandardRequestMethod;

$client = new PayabliClient(
    apiKey: 'YOUR_API_KEY_HERE',
);
$client->notification->updateNotification(
    '1717',
    new NotificationStandardRequest([
        'content' => new NotificationStandardRequestContent([
            'eventType' => NotificationStandardRequestContentEventType::ApprovedPayment->value,
        ]),
        'frequency' => NotificationStandardRequestFrequency::Untilcancelled->value,
        'method' => NotificationStandardRequestMethod::Email->value,
        'ownerId' => 136,
        'ownerType' => 0,
        'status' => 1,
        'target' => 'newemail@email.com',
    ]),
);

```

```swift
import Foundation

let headers = [
  "requestToken": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "content": ["eventType": "ApprovedPayment"],
  "frequency": "untilcancelled",
  "method": "email",
  "ownerId": 136,
  "ownerType": 0,
  "status": 1,
  "target": "newemail@email.com"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/Notification/1717")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

A successful response returns the ID of the updated notification as `responseData`:

### Response (200)

```json
{
  "responseText": "Success",
  "isSuccess": true,
  "responseCode": 1,
  "responseData": 1717
}
```

## Delete a notification

Send a DELETE request to `/api/Notification/{notificationId}` to remove an existing notification. See the [API reference](/developers/api-reference/notification/delete-notification) for full documentation.

This example deletes notification ID `1717`:

### Request

DELETE [https://api-sandbox.payabli.com/api/Notification/\{nId}](https://api-sandbox.payabli.com/api/Notification/\{nId})

```curl
curl -X DELETE https://api-sandbox.payabli.com/api/Notification/1717 \
     -H "requestToken: <apiKey>"
```

```typescript
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient({
        apiKey: "YOUR_API_KEY_HERE",
    });
    await client.notification.deleteNotification("1717");
}
main();

```

```python
from payabli import payabli

client = payabli(
    api_key="YOUR_API_KEY_HERE",
)

client.notification.delete_notification(
    n_id="1717",
)

```

```java
package com.example.usage;

import io.github.payabli.api.PayabliPayabliApiOasClient;

public class Example {
    public static void main(String[] args) {
        PayabliPayabliApiOasClient client = PayabliPayabliApiOasClient
            .builder()
            .apiKey("YOUR_API_KEY_HERE")
            .build();

        client.notification().deleteNotification("1717");
    }
}
```

```ruby
require "payabli"

client = Payabli::Client.new(api_key: "YOUR_API_KEY_HERE")

client.notification.delete_notification(n_id: "1717")

```

```csharp
using PayabliPayabliApiOas;
using System.Threading.Tasks;

namespace Usage;

public class Example
{
    public async Task Do() {
        var client = new PayabliPayabliApiOasClient(
            apiKey: "YOUR_API_KEY_HERE"
        );

        await client.Notification.DeleteNotificationAsync(
            "1717"
        );
    }

}

```

```go
package example

import (
    context "context"

    client "github.com/payabli/sdk-go/client"
    option "github.com/payabli/sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithApiKey(
            "YOUR_API_KEY_HERE",
        ),
    )
    client.Notification.DeleteNotification(
        context.TODO(),
        "1717",
    )
}

```

```php
<?php

namespace Example;

use Payabli\PayabliClient;

$client = new PayabliClient(
    apiKey: 'YOUR_API_KEY_HERE',
);
$client->notification->deleteNotification(
    '1717',
);

```

```swift
import Foundation

let headers = ["requestToken": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/Notification/1717")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

A successful response returns the ID of the deleted notification as `responseData`:

### Response (200)

```json
{
  "responseText": "Success",
  "isSuccess": true,
  "responseCode": 1,
  "responseData": 1717
}
```

## Related resources

See these related resources to help you get the most out of Payabli.

* **[Notifications and reports overview](/guides/pay-ops-notifications-webhooks-overview)** - Get automated reports and notifications for key events

- **[Webhook notification response reference](/guides/pay-ops-webhooks-payloads)** - Learn more about the payload for each webhook notification response body

* **[Webhook quickstart](/guides/pay-ops-developer-webhooks-quickstart)** - Learn to use example code to set up webhooks for payment notifications