Webhooks and integration responsibilities

Use webhooks to notify your integration when a Contract event occurs, such as signing.

The same integration can create the Contract and respond to its events. Other integrations can also respond.

For example, after a Contract is signed:

• An HR system can create or update an employee.
• A CRM can update the related deal.
• A document system can store the signed Contract.

How the handoff works

1. A Contract event occurs in Oneflow, such as contract:sign.
2. Oneflow checks the registered webhook filters.
3. Oneflow sends an HTTP POST request to each matching registered callback URL.
4. The receiving integration validates the request and retrieves the Contract data or files it needs.
5. The integration performs the action in the destination system.

Trigger event

A typical trigger is:

• contract:sign

Use an EVENT_TYPE rule to choose the event. To limit notifications to Contracts associated with a particular Blueprint, add a BLUEPRINT rule to the same filter_rules array. Both rules must then match.

{
  "filters": [
    {
      "filter_rules": [
        {
          "type": "EVENT_TYPE",
          "values": ["contract:sign"]
        },
        {
          "type": "BLUEPRINT",
          "values": [860001]
        }
      ]
    }
  ]
}

See Create a webhook for the complete request.

Filter rules within the same filter must all match. Separate filters act as alternative matches. If the filter criteria match, Oneflow sends a webhook notification.

Webhook notification

Oneflow sends a JSON payload to the registered callback URL.

{
  "contract": {
    "id": 1001
  },
  "callback_id": "eaf850991bb7c273a56dcdeb265d30006fdc9de0",
  "events": [
    {
      "created_time": "2026-07-23T10:00:00+0000",
      "id": 98001,
      "type": "contract:sign"
    }
  ],
  "signature": "7a581695d9ff8c41de4d85554b6852f7cf6f97b0"
}

The notification payload consists of the Contract and event identifiers only.
The notification tells you which Contract and event to process.

Use the identifiers in the notification to retrieve what the destination needs:

• Get a Contract
• Get Contract data fields
• Get a Contract event
• The relevant Contract file endpoint when you need the signed document

Retrieve the current Contract state before performing the destination action. A user can change mapped values between Contract creation and signing.

What Oneflow handles

Oneflow:

• Detects Contract events.
• Applies the webhook filters.
• Sends a signed notification to each matching callback URL.
• Retries the notification when the callback does not return HTTP 200.
• Provides mapped Contract data according to the receiving Integration's context.

What your integration handles

1. Validate the notification

Confirm the callback route, the expected customer, the required fields, and the signature.

Oneflow calculates the signature as:

sha1(callback_id + sign_key)

Calculate the same hash and compare it with the signature in the request.

2. Prevent duplicate actions

Oneflow can deliver the same notification more than once. The callback_id remains the same across retries.

Use callback_id as an idempotency key. For example, a retry of contract:sign must not create a second employee in HiBob.

3. Retrieve the required Contract data

Use the receiving Integration's API token to retrieve the required contract data.

As an example, you can get the current mapped fields with Get Contract data fields, and it will return fields as follows.

{
  "_private_ownerside": {
    "custom_id": "given_name"
  },
  "id": 140001,
  "name": "First name",
  "value": "Alice"
}

Use custom_id to identify fields. Do not rely on display names.

The same Playbook field can expose different custom_id values to different Integrations. Each Integration receives the identifier defined by its Blueprint mapping.

4. Perform the destination action

Your integration decides what happens next. For example:

• Create an employee in an HR system.
• Update an existing CRM or ERP record.
• Retrieve and attach the signed Contract.
• Store the signed Contract in an archive.

Oneflow does not infer which destination record to update. If the action targets an existing record, use a stable external identifier stored in a mapped data field.

5. Store destination identifiers when needed

Returning an ID in the webhook response does not save it in Oneflow.

If Oneflow must retain a destination record ID, write it to a mapped Contract data field through the Update Contract data field.

6. Return a successful response

Return HTTP 200 after you process the notification or safely queue it for processing. Oneflow ignores the response body.

Any other status causes a retry. Oneflow makes up to 10 delivery attempts.

The Public API webhook documentation does not define an event-ordering guarantee. Process each event independently and make every operation safe to repeat.

What to log

Record enough information to trace the handoff:

• Customer or Oneflow account
• Contract ID
• Event ID and type
• callback_id
• Processing result
• Destination record ID
• Retry count

Do not log API tokens, signing keys, full documents, or unnecessary personal data.

Test the use case

Confirm that:

• Only Contracts connected to the intended Blueprint trigger the webhook.
• The destination uses the current mapped values.
• Repeating the same callback_id does not repeat the destination action.
• Missing mappings or destination identifiers produce a controlled failure.
• Signed files reach the correct destination when the use case requires them.
• Successful processing returns HTTP 200.

Related topics

• Key concepts
• Core building blocks
• Quick start: Blueprints and Playbooks
• Migration guide