---
title: "Webhook notifications"
url: "https://pitchghost.com/docs/notifications/webhooks"
description: "Send a Ghost's new Finds to your own endpoint as JSON, with the request, headers, payload, grouping and after-webhook options."
---

A webhook sends a Ghost’s new Finds to a URL you control, as JSON, as soon as a scan finishes. Use it to push Finds into your own CRM, database or automation.

## Set up a webhook

1.  Go to Ghosts, open the Ghost and choose Notifications.
2.  Turn on Webhook and enter your Webhook URL.
3.  To authenticate requests, enter a token under Authorization (optional). Leave out the word “Bearer”. PitchGhost adds it.
4.  Tick Group requests or set After webhook options if you want them.
5.  Click Save.

## When requests are sent

PitchGhost sends requests when a scan finishes with at least one new Find. You get one request per Find. With Group requests on, you get one request per scan, with every Find in a `finds` array.

A Find you create from a scanned item with Make a Find is sent only if you tick Trigger webhook when you convert it.

## The request

| Part | Value |
| --- | --- |
| Method | POST |
| Headers | Content-Type: application/json and User-Agent: Pitchie. With a token, also Authorization: Bearer <token> |
| Timeout | PitchGhost waits up to 30 seconds for a response |

Requests are not signed. Check the `Authorization` header in your endpoint to make sure a request came from PitchGhost.

## The payload

A request for one Find looks like this.

```
{
    "ghost": {
        "id": "6f1c2b9e-...",
        "name": "Payroll Switchers",
        "type": "Reddit"
    },
    "scan": {
        "id": 48213,
        "status": "succeeded",
        "created_at": "2026-11-10T14:00:03.512Z",
        "updated_at": "2026-11-10T14:02:41.208Z"
    },
    "find": {
        "id": "b7d0e4a1-...",
        "findDate": "2026-11-10T14:02:39.870Z",
        "data": { "...": "the post, shaped by platform" },
        "contact": {
            "id": "0a9f33c2-...",
            "type": "person",
            "firstName": "Dana",
            "lastName": "Ortiz",
            "displayName": "Dana Ortiz",
            "firstSource": "reddit",
            "profileUrl": "https://...",
            "firstSeenDate": "2026-10-02T09:15:00.000Z",
            "contactInfo": [
                {
                    "type": "reddit",
                    "value": "dana_runs_payroll",
                    "url": "https://www.reddit.com/user/dana_runs_payroll"
                }
            ]
        }
    }
}
```

With Group requests on, `find` is replaced by `finds`, an array of the same Find objects.

| Field | What it holds |
| --- | --- |
| ghost.id, ghost.name | The Ghost’s ID and name |
| ghost.type | The Ghost type, one of Twitter, LinkedIn, Reddit, Facebook, LinkedIn_People or LinkedIn_Company |
| scan.id | The scan’s ID |
| scan.status | The scan’s status when the request was built |
| scan.created_at, scan.updated_at | When the scan started and last changed |
| find.id | The Find’s ID, the same as in the app and the CSV export |
| find.findDate | When the Find was found |
| find.data | The post as PitchGhost stores it. Its fields depend on the platform, so read ghost.type first |
| find.contact | The poster, or null if the Find has no contact |
| contact.type | person or company |
| contact.firstSource | Where the contact was first found, one of twitter, linkedIn, reddit, facebook or manual |
| contact.profileUrl | The URL of the contact’s profile picture, not their profile page |
| contact.contactInfo | Each profile or address known for the contact, with its type (email, twitter, linkedIn, reddit or facebook), value and url |

Finds whose stored data PitchGhost can’t read are left out of the request.

## After webhook options

Turn on After webhook options to change the Finds once they are sent. Delete deletes every Find delivered to the webhook, for when PitchGhost is only a pipe into your own system. Mark as read marks them as read so they do not count as unread on the Finds page.

Warning

-   **No retries.** Each request is sent once. If your endpoint is down or times out, those Finds are not sent again.
-   **After webhook options run even if your endpoint returns an error.** PitchGhost does not check the response status, so with Delete on, the Finds are deleted anyway. They are kept only when the request cannot complete at all, such as a timeout or a connection failure.

If your endpoint is not fully reliable, use Mark as read so the Finds stay in PitchGhost.