Skip to content

Pointr MapScale API Webhook Guide

All configurations and endpoints related to Pointr MapScale API Webhook are explained one by one below. There must be at least one active webhook configuration for the webhook to run smoothly. When more than one configuration is added, notifications are sent to all added configurations.

Appsettings Configuration

We use some parameters in the application while making webhook notifications. Although these are default parameters, if client-based changes are desired, the following parameters must be corrected according to the client. If you want to change these values, you need to change them from the appsettings.json file in the application.

"WebhookSettings": {
  "MailSendingThreshold": 25
},
"ScheduledJobSettings": {
  "WebhookSchedulerMinutes": 1,
  "WebhookAlertMailSchedulerMinutes": 30
}
  1. MailSendingThreshold: The threshold point that specifies how many error webhook notifications must be received before mail can be sent. Defaut is 25.
  2. WebhookSchedulerMinutes : Specifies how often webhook notifications should be made. When the timer is triggered, all expected webhook notifications are sent in order. Default is 1 minute.
  3. WebhookAlertMailSchedulerMinutes: Timer that determines how long to send a mail for webhook notifications that have received errors. Default is triggered every 30 minutes, if there are webhook notifications that cannot be sent in the system, mail is sent to the mail addresses in the retryFailureNotifyAddress specified in the webhook configuration.

Endpoints

Create Webhook Configuration

This endpoint allows you to create a new webhook configuration. No notify is sent to any address without webhook configuration. First of all, you need to add a webhook configuration.

Requirements:

  • Url must be unique.
  • Header key and value is optional. If you have webhook security header information, you can write in this section.
  • RetryCountMax optional, default is 20 and must be in the range 0-20.
  • retryIntervalInSecond optional, default is 60 and must be in the range 60-900.
  • retryFailureNotifyAddress is an optional field. It is used for notification when the threshold point is reached in webhook submissions.

  • isEnabled is used to start notifications immediately. Notifications will not be sent until it is enabled.

  • Method: POST

  • Endpoint: clients/{clientInternalIdentifier}/map-jobs/configurations/webhooks
  • Description: Creates webhook configurations under a specific client identifier.
  • Request Payload: 
{
    "url": "https://xyz.com/webhook",
    "headerKey": "Authorization",
    "headerValue": "Bearer xxxxx",
    "retryCountMax": 20,
    "retryIntervalInSecond": 60,
    "retryFailureNotifyAddress": [
        "xxx@pointr.tech",
        "yyy@pointr.tech",
        "zzz@pointr.tech"
    ]
}
  • Response Data: 
{
    "result": {
        "webhookIdentifier": 1
    },
    "statusCode": 200
}

Update Webhook Configuration

This endpoint allows you to update an existing webhook configuration. When updated, all notifications that could not be sent, received an error or are waiting to be sent are tried to be sent again to the newly updated webhook address.

Note

Not all sent notifications are sent again.

Requirements:

  • Url must be unique.
  • Header key and value is optional. If you have webhook security header information, you can write in this section.
  • RetryCountMax optional, default is 20 and must be in the range 0-20.
  • retryIntervalInSecond optional, default is 60 and must be in the range 60-900.
  • retryFailureNotifyAddress is an optional field. It is used for notification when the threshold point is reached in webhook submissions.

  • isEnabled is used to start notifications immediately. Notifications will not be sent until it is enabled.

  • Method: PUT

  • Endpoint: clients/{clientInternalIdentifier}/map-jobs/configurations/webhooks/{identifier}
  • Description: Updates a specific webhook configuration under a specific client identifier and unique webhook configuration identifier.
  • Request Payload:
{
    "url": "https://xyz.com/webhook",
    "headerKey": "Authorization",
    "headerValue": "Bearer xxxxx",
    "retryCountMax": 20,
    "retryIntervalInSecond": 60,
    "retryFailureNotifyAddress": [
        "xxx@pointr.tech",
        "yyy@pointr.tech",
        "zzz@pointr.tech"
    ]
}
  • Response Data:
{
    "result": {
        "webhookIdentifier": 1
    },
    "statusCode": 200
}

Delete Webhook Configuration

This endpoint allows you to delete a specific webhook configuration. When a configuration is deleted, it is deleted as hard delete. It cannot be undone.

{
    "result": "",
    "statusCode": 200
}

Get Webhook Configurations

This endpoint allows you to retrieve webhook configurations. 

{
    "result": [
        {
            "id": 1,
            "url": "https://xyz.com/webhook",
            "headerKey": "Authorization",
            "headerValue": "Bearer xxxxx",
            "retryCountMax": 20,
            "retryIntervalInSecond": 60,
            "retryFailureNotifyAddress": [
                "xxx@pointr.tech",
                "yyy@pointr.tech",
                "zzz@pointr.tech"
            ]
        }
    ],
    "statusCode": 200
}

Get Webhook Configuration

This endpoint allows you to retrieve a specific webhook configuration.

{
    "result": {
        "id": 1,
        "url": "https://xyz.com/webhook",
        "headerKey": "Authorization",
        "headerValue": "Bearer xxxxx",
        "retryCountMax": 20,
        "retryIntervalInSecond": 60,
        "retryFailureNotifyAddress": [
            "xxx@pointr.tech",
            "yyy@pointr.tech",
            "zzz@pointr.tech"
        ]
    },
    "statusCode": 200
}

Webhook Operations

This group of endpoints performs webhook operations.

Get Webhooks

This endpoint allows you to retrieve webhooks.

{
    "result": {
        "webhooks": [
            {
                "id": "6740cf80-35dc-44d2-87f2-95c4c492c6b4",
                "message": "{\"cid\":\"63abe223-cbae-4000-97e1-d1068b987065\",\"sid\":1,\"bid\":1,\"userName\":\"System\",\"dateTimeEpoch\":1713969833,\"operationType\":\"UPDATE\",\"contentType\":\"MAPJOB\"}",
                "responseMessage": "\"Webhook received successfully.\"",
                "responseStatusCode": 200,
                "tryCount": 21,
                "firstRequestDateTime": "2024-04-24T14:43:53.585606+00:00",
                "lastRequestDateTime": "2024-04-25T13:07:02.525931+00:00",
                "webhookConfigurationUrl": "https://xyz.com/webhook",
                "webhookConfigurationHeaderKey": "Authorization",
                "webhookConfigurationHeaderValue": "Bearer xxxxx"
            }
        ],
        "totalCount": 1,
        "pageNumber": 1
    },
    "statusCode": 200
}

Resend Webhook

With this endpoint, you can resend any webhook request in the webhook list. The purpose of this was developed so that if you get an error from any webhook request, you can manually try to send a request again instantly.

{
    "message": "Resending webhook is successfull",
    "statusCode": 200
}

Endpoint List with Request Body

In the table below, there are examples and directions of webhook notifications that may occur in all endpoints. You can make your developments through reference notifications.

Endpoint Behaviour Webhook Request Body
In case of a status change every time the schedular runs Mapscale will send a new notification in any case where the mapjob status changes at runtime. 
 { 
     “cid”: “d744aaf9-d3dc-4d2f-9642-543b7b338b04”, 
     “sid”: 1, 
     “bid”: 1, 
     “username”: “System”, 
     “dateTimeEpoch”: 1714330101, 
     “operationType”: “UPDATE”, 
     “contentType”: “MAPJOB”, 
     “mapJobId”: 12, 
     “status”: 3, 
     “statusDescription”: “AwaitingReview” 
 }

If you need more information, you can visit our API Reference page. This enhancement will be available in v8.12 and above.

Last update: September 3, 2024
Back to top